Server-Side Auth

Server-side authentication is used for backend services, deployed customer applications, and inter-service communication. These methods are not intended for end-user browsers.

Deployment credentials

Deployed customer applications use a pair of headers to authenticate with the HiveForge API via the SDK:

Header	Description
`X-Deployment-ID`	The unique identifier for the deployment
`X-Deployment-Secret`	The secret key generated at deployment time

How it works

When a customer app is deployed through HiveForge, the platform generates a deployment ID and secret
The SDK sends both headers with every request
The API validates the secret against the stored deployment record
The deployment's tier determines which features and rate limits apply

SDK usage

import { HiveForgeClient } from '@producthacker/hiveforge-sdk'
 
const client = new HiveForgeClient({
  deploymentId: process.env.HIVEFORGE_DEPLOYMENT_ID!,
  deploymentSecret: process.env.HIVEFORGE_DEPLOYMENT_SECRET!,
  baseUrl: 'https://api.hiveforge.dev',
})
 
// The SDK automatically includes X-Deployment-ID and X-Deployment-Secret headers
const entitlements = await client.getEntitlements()

Direct HTTP usage

If you are not using the SDK, send the headers manually:

const response = await fetch('https://api.hiveforge.dev/api/v1/entitlements', {
  headers: {
    'X-Deployment-ID': process.env.HIVEFORGE_DEPLOYMENT_ID!,
    'X-Deployment-Secret': process.env.HIVEFORGE_DEPLOYMENT_SECRET!,
    'Content-Type': 'application/json',
  },
})

⚠️

Deployment credentials should only be used in server-side environments. Never expose them in client-side code or browser JavaScript.

Service role key

The Supabase service role key bypasses Row-Level Security (RLS) and has full access to the database. It is used for administrative operations that run outside of a user context.

import { createClient } from '@supabase/supabase-js'
 
const supabaseAdmin = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!, // bypasses RLS
)
 
// Admin operations (e.g., managing users, seeding data)
const { data } = await supabaseAdmin
  .from('profiles')
  .select('*')
  .limit(10)

🚫

The service role key has unrestricted access. Never use it in client-side code, expose it in API responses, or commit it to version control.

MCP Service Key

The MCP (Model Context Protocol) service key authenticates inter-service calls between MCP tool servers and the HiveForge API.

Header

Header	Value
`X-MCP-Service-Key`	The shared secret configured in `HIVEFORGE_MCP_SERVICE_KEY` env var

Usage

const response = await fetch('https://api.hiveforge.dev/api/v1/mcp/tools/execute', {
  method: 'POST',
  headers: {
    'X-MCP-Service-Key': process.env.HIVEFORGE_MCP_SERVICE_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'search_documents',
    arguments: { query: 'deployment status' },
  }),
})

curl -X POST https://api.hiveforge.dev/api/v1/mcp/tools/execute \
  -H "X-MCP-Service-Key: $MCP_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool": "search_documents", "arguments": {"query": "deployment status"}}'

Admin service key

The HIVEFORGE_SERVICE_KEY is used for platform-level admin endpoints (deployment management, system diagnostics). It is sent via the X-Service-Key header.

# Check deployment status
curl https://api.hiveforge.dev/admin/status/dep_abc123 \
  -H "X-Service-Key: $HIVEFORGE_SERVICE_KEY"
 
# Trigger a deployment
curl -X POST https://api.hiveforge.dev/admin/deploy/dep_abc123 \
  -H "X-Service-Key: $HIVEFORGE_SERVICE_KEY"

When to use each method

Scenario	Method	Header
Customer app calling HiveForge API	Deployment credentials	`X-Deployment-ID` + `X-Deployment-Secret`
Admin script managing deployments	Admin service key	`X-Service-Key`
MCP tool server executing tools	MCP service key	`X-MCP-Service-Key`
Backend seeding data / admin ops	Supabase service role key	Supabase client config
Automated CI/CD pipeline	API key	`Authorization: Bearer hf_live_...`

Environment variables reference

Variable	Description	Used by
`HIVEFORGE_DEPLOYMENT_ID`	Deployment identifier	SDK, customer apps
`HIVEFORGE_DEPLOYMENT_SECRET`	Deployment secret	SDK, customer apps
`HIVEFORGE_SERVICE_KEY`	Admin API key	Platform admin scripts
`HIVEFORGE_MCP_SERVICE_KEY`	MCP authentication key	MCP tool servers
`SUPABASE_SERVICE_ROLE_KEY`	Supabase admin key (bypasses RLS)	Backend admin operations

OAuth & SSO Getting Started