Authentication and API keys

An API key lets your backend call HivemindOS for one account. Keep it on your server, give it only the access its job needs, and replace it if it is ever exposed.

Four controls decide what a key can do:

1. Scopes decide which kinds of actions the key may perform.
2. Service access decides which managed services the key may reach.
3. Operation access decides the exact managed capabilities and SuperAgent API endpoints the key may call.
4. Operation limits cap how often or how much the key may use each operation.

All four controls must allow a request. If any control says no, the request is rejected.

Create the first key

The first key is created with an existing HivemindOS credit token. This is the only SuperAgent API request that accepts X-HivemindOS-Credit-Token in place of a bearer key.

curl https://api.hivemindos.app/v1/api-keys \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: backend-root-key-v1" \
  --header "X-HivemindOS-Credit-Token: $HIVEMINDOS_CREDIT_TOKEN" \
  --data '{
    "label": "Backend root",
    "scopes": [
      "services:read",
      "services:invoke",
      "credits:read",
      "api_keys:manage"
    ],
    "allowedServices": ["hive-research", "managed-workflows"],
    "allowedOperations": [
      "actions.list",
      "services.invoke.hive-research.analyses.create",
      "runs.create.hive-research.analyses.create"
    ],
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }'

The successful response includes secret. Its hmos_live_... value is returned only at creation time. Save it immediately in your secret manager. Later key listings return only a prefix and metadata.

Authenticate requests

Send the SuperAgent API key as a bearer token:

curl https://api.hivemindos.app/v1/services \
  --header "Authorization: Bearer $HIVEMINDOS_API_KEY"

Do not put the key in a URL or request body. Keep the API call on infrastructure you control; a browser or mobile client should call your backend, which then calls HivemindOS.

The remote MCP at https://api.hivemindos.app/mcp uses the same bearer key. An MCP key must include services:read and actions.list, then only the exact additional actions it should be able to discover and call.

{
  "allowedOperations": [
    "capabilities.list",
    "services.invoke.hive-research.analyses.create",
    "runs.create.hive-research.analyses.create",
    "runs.read"
  ]
}

const workerKey = await hive.apiKeys.create(
  {
    label: "Research worker",
    scopes: ["services:read", "services:invoke", "runs:read", "runs:write"],
    allowedServices: ["hive-research"],
    allowedOperations: [
      "capabilities.list",
      "services.invoke.hive-research.analyses.create",
      "runs.create.hive-research.analyses.create",
      "runs.read",
    ],
    expiresAt: "2026-12-01T00:00:00.000Z",
    limits: {
      "services.invoke.hive-research": {
        requestsPerMinute: 20,
        maxConcurrent: 2,
      },
    },
  },
  { idempotencyKey: "research-worker-2026-12" },
);

Use idempotency keys

Every mutation and spending action requires Idempotency-Key. Use a stable identifier for one logical action, such as an order id or job id generated by your system.

Idempotency-Key: order_01J6M1Q64NQH8S1QKC9D7G3V3T

An idempotency key must be 8–200 characters and may contain letters, digits, colons, periods, underscores, and hyphens. Repeating the same key with the same input returns the stored result. Reusing it with different input returns HTTP 409.

Idempotency is isolated by API key. Two sibling keys may use the same external job id without replaying one another’s response.

Use one key for one responsibility

Use separate keys for separate responsibilities:

• A catalog key with only read scopes.
• One worker key for each service or workload.
• A funding key with credits:read and credits:write, restricted to credits.balance.read and credits.x402.topUp.
• A wallet execution key without approval authority.
• A reviewer key with approvals:write but no wallet or trading execution scope.
• A key-management credential kept outside ordinary application workers.

This separation prevents one compromised component from gaining unrelated services or approving the action it proposed.

A funding key controls who may ask the configured x402 payer to buy Agent Credits. It does not expose the official revenue wallet as a choice and it cannot credit another HivemindOS account. Keep the payer signer in a separate secret boundary and require your own user approval before signing each payment.

Rotate or revoke a key

1. Create a new child key with the same or narrower policy.
2. Add it to the server-side secret manager.
3. Move traffic to the new key and verify successful requests.
4. Revoke the old key with DELETE /api-keys/{id} and a unique idempotency key.

Revocation is immediate and also stops webhooks created under that key authority from receiving new events.

Next: limit individual operations or review the complete scope and endpoint reference.