API Keys

API keys provide programmatic access to the HiveForge API. They are scoped to an organization and support granular permissions.

Key format

HiveForge API keys use a prefixed format that indicates the environment:

Creating API keys

Via the API

Requires owner or admin role in the organization.

const response = await fetch('https://api.hiveforge.dev/api/v1/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'CI/CD Pipeline Key',
    scopes: ['read', 'write', 'deployments'],
    expires_at: '2027-01-01T00:00:00Z', // optional
    metadata: { environment: 'production' }, // optional
  }),
})
 
const { key, id, name, key_prefix, scopes } = await response.json()
// key = "hf_live_a1b2c3d4..." -- save this now!

Using API keys

Send the key as a Bearer token in the Authorization header:

const response = await fetch('https://api.hiveforge.dev/api/v1/organizations', {
  headers: {
    'Authorization': 'Bearer hf_live_a1b2c3d4e5f6...',
    'Content-Type': 'application/json',
  },
})

The API key middleware intercepts the request, validates the key, and attaches the organization context and scopes to the request. Downstream route handlers enforce scope requirements.

Available scopes

Basic scopes

Feature-specific scopes

Scope hierarchy

Parent scopes automatically include their child scopes. For example, granting webhooks also grants webhooks:read, webhooks:write, and webhooks:delete. The admin scope includes everything.

admin
  +-- read, write, delete
  +-- chat (chat:read, chat:write)
  +-- webhooks (webhooks:read, webhooks:write, webhooks:delete)
  +-- api_keys (api_keys:read, api_keys:write, api_keys:delete)
  +-- members (members:read, members:write, members:delete)
  +-- billing (billing:read, billing:write)
  +-- audit (audit:read)
  +-- deployments (deployments:read, deployments:write, deployments:delete)

Managing keys

List keys

curl https://api.hiveforge.dev/api/v1/api-keys \
  -H "Authorization: Bearer $JWT_TOKEN"

Update a key

curl -X PATCH https://api.hiveforge.dev/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Key Name",
    "scopes": ["read", "chat"]
  }'

Revoke a key

curl -X DELETE https://api.hiveforge.dev/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer $JWT_TOKEN"

Key rotation best practices

1. Set expiration dates. Always create keys with an expires_at value. Avoid permanent keys.
2. Use minimal scopes. Grant only the scopes each integration actually needs.
3. Rotate regularly. Create a new key, update your integration, then revoke the old key.
4. Monitor usage. Check audit logs for unexpected API key activity.
5. Use separate keys per integration. Do not share a single key across multiple services.
6. Store securely. Use environment variables or a secrets manager. Never commit keys to version control.

Error responses