REST & policy API.

Overview

Every resource follows the same shape. Here's the full surface at a glance.

Authentication

Admin keys (hk_live_…) authenticate management calls. Agent tokens (hk_agt_…) authenticate actions at the gateway and are scoped to a role. Pass either as a bearer token.

curl https://api.hivekey.ai/v1/agents \
  -H "Authorization: Bearer hk_live_8fK2…aR9" \
  -H "HiveKey-Version: 2026-04-01"

An agent is a verifiable identity bound to an owner and a role. Create one, retrieve it, or kill-switch it.

POST /v1/agents

Body parameters

curl https://api.hivekey.ai/v1/agents \
  -H "Authorization: Bearer hk_live_…" \
  -d '{"name":"helpdesk-bot",
       "role":"support-agent",
       "owner":"sam@acme.com"}'

{
  "id": "agt_5Kd0pN",
  "object": "agent",
  "name": "helpdesk-bot",
  "role": "support-agent",
  "owner": "sam@acme.com",
  "status": "active",
  "created": 1775923200
}

A role bundles scope grants and guard rules. Every update creates a new immutable revision; agents always run the latest.

PATCH /v1/roles/:name

curl -X PATCH \
  https://api.hivekey.ai/v1/roles/support-agent \
  -H "Authorization: Bearer hk_live_…" \
  -d '{"scope":{"allow":["mail.read",
       "mail.send","crm.read"]}}'

{
  "object": "role",
  "name": "support-agent",
  "revision": 4,
  "scope": { "allow": ["mail.read",
    "mail.send", "crm.read"] },
  "guards": 2,
  "agents_affected": 12
}

Dry-run a decision without performing the action. Useful for CI checks and policy testing — same engine the gateway uses in the path.

POST /v1/policies/evaluate

curl https://api.hivekey.ai/v1/policies/evaluate \
  -H "Authorization: Bearer hk_live_…" \
  -d '{"role":"support-agent",
       "action":"mail.send",
       "input":{"to":"x@gmail.com"}}'

{
  "verdict": "deny",
  "matched_guard": "approved-domains",
  "reason": "domain 'gmail.com' not in
    allowlist",
  "dry_run": true
}

The immutable action log. Filter by agent, verdict, or time; paginate with a cursor. Stream the same events to your SIEM via webhooks or the OCSF export.

GET /v1/audit/events

Query parameters

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "evt_9hT1zP",
      "ts": 1775923331,
      "agent": "helpdesk-bot",
      "owner": "sam@acme.com",
      "action": "mail.send",
      "verdict": "deny",
      "matched_guard": "approved-domains",
      "request_id": "act_2Nf9kR"
    }
  ],
  "next_cursor": "evt_9hT1zP"
}

Mint a short-lived, role-scoped token for an agent. The secret is shown once. Revoke it any time — or kill-switch the agent to revoke all of its tokens.

POST /v1/tokens

{
  "object": "token",
  "id": "tok_7Yb3wM",
  "agent": "helpdesk-bot",
  "secret": "hk_agt_3pQ…shown_once",
  "expires": 1776009600,
  "scopes": ["mail.read", "mail.send"]
}

Subscribe to verdicts and lifecycle events. Each delivery is signed with an HMAC (HiveKey-Signature header) and is replay-safe via a timestamp.

Event types

{
  "id": "whk_1aF…",
  "type": "action.denied",
  "created": 1775923331,
  "data": {
    "agent": "helpdesk-bot",
    "action": "mail.send",
    "matched_guard": "approved-domains",
    "request_id": "act_2Nf9kR"
  }
}

Error codes