Authentication Overview

HiveForge supports four authentication mechanisms, each designed for a different use case. Choose the right one based on who or what is making the request.

Authentication methods

Method	Header	Use case
Supabase JWT	`Authorization: Bearer <token>`	End-users accessing the platform via browser or mobile app
API Keys	`Authorization: Bearer hf_live_...`	Programmatic access from your backend services
Deployment Credentials	`X-Deployment-ID` + `X-Deployment-Secret`	SDK and proxy calls from deployed customer apps
MCP Service Key	`X-MCP-Service-Key`	Inter-service calls for MCP tool execution

How it works

                        HiveForge API
                             |
         +-------------------+-------------------+
         |                   |                   |
    JWT Tokens          API Keys          Deployment Creds
    (end users)       (programmatic)      (SDK / proxy)
         |                   |                   |
   Supabase Auth      Key validation      Secret matching
   HS256 / RS256      Scope checking      Tier entitlements

1. Supabase JWT

The default authentication method for end-users. When a user signs in through the HiveForge web app (email/password or OAuth), Supabase issues a JWT that is sent as a Bearer token. The API verifies the token using either the JWT secret (HS256) or JWKS endpoint (RS256).

Best for: Browser-based applications, mobile apps, any user-facing client.

2. API Keys

Prefixed keys (hf_live_... for production, hf_test_... for sandbox) with granular scope-based permissions. Keys are tied to an organization and created by admin or owner users. The API key middleware validates the key and attaches scopes to the request for downstream enforcement.

Best for: Server-to-server integrations, CI/CD pipelines, automation scripts.

3. Deployment Credentials

A pair of headers (X-Deployment-ID and X-Deployment-Secret) used by the HiveForge SDK when a deployed customer application communicates with the platform. These credentials identify the deployment and determine tier-based entitlements.

Best for: Customer SaaS apps deployed through HiveForge, SDK initialization.

4. MCP Service Key

A shared secret sent via X-MCP-Service-Key header for Model Context Protocol inter-service calls. This authenticates tool invocations between the MCP server and the HiveForge API.

Best for: MCP tool servers, internal service-to-service communication.

All API requests must use HTTPS in production. The base URL for the HiveForge API is https://api.hiveforge.dev.

Choosing the right method

Building a web app? Use JWT tokens via Supabase Auth.
Calling the API from a backend? Use API keys with appropriate scopes.
Using the HiveForge SDK in a deployed app? Use deployment credentials.
Connecting an MCP tool server? Use MCP service key.

Project Structure JWT Tokens