Documentation

API reference

Agent API keys use Authorization: Bearer bhf_sk_xxx. Dashboard routes use developer session cookies.

POST/api/agents

Add a native or connected agent and return the API key once.

POST/api/permissions

Create a permission for the authenticated agent.

POST/api/verify

Evaluate whether an agent can perform an action.

GET/api/logs/[agentId]

Read recent verification logs for the authenticated agent.

POST/api/agents/[agentId]/rotate-key

Rotate an agent API key and return the new key once.

Agent metadata

POST /api/agents remains compatible with { "name": "Jasper Shopping Agent" }. It also accepts optional connected-agent metadata.

connected-agent.json

{
  "name": "Ollie",
  "agentType": "connected",
  "provider": "ollie",
  "externalAgentId": "optional",
  "externalAgentLabel": "Jasper's Ollie assistant",
  "description": "Family/personal assistant used for daily planning"
}

Permission shape

A permission is an action plus constraints. The current public API keeps vendor and allowedVendors for compatibility; resourceis also accepted by /api/verify and passport preview routes as a clearer alias. amount is optional and mainly relevant to transaction-like permissions.

Agent descriptions are informational. Permissions are the source of truth for what an agent may do. Use allowedActions and blockedActions to make permissions explicit so external agents can read them from the passport page.

permission.json

{
  "agentId": "agent_xxx",
  "action": "access_data",
  "resource": "gmail.com",
  "scope": "read-only gmail access",
  "allowedActions": ["read labels", "summarize messages", "provide pricing metrics"],
  "blockedActions": ["send email", "delete messages", "schedule events"],
  "requiresApproval": true,
  "template": "access_data",
  "constraints": {
    "allowedVendors": ["gmail.com"],
    "expiresAt": "2099-05-01T23:59:59Z"
  }
}

Manual passport tests

Passport routes use a separate tokenized link. Send the bhf_pass_token as a bearer token; generated UI links keep it in the URL fragment. Passport links intentionally expose the agent's allowed permission scopes so external agents can read what they are permitted to do. They cannot create permissions, rotate keys, read logs, or expose API keys, webhook secrets, developer identity, or internal IDs.

A passport token is not an API key. It only allows viewing the scoped passport and running manual preview checks for one agent. Treat it like a secret — anyone with the token can view the allowed scopes.

GET/api/passport/[agentId]

Read safe public passport data: agent metadata and active permission scopes. Returns passportVersion, mode, agent, permissions, and limitations. Never returns API keys, logs, developer identity, or internal IDs.

POST/api/passport/[agentId]

Run a manual allow/deny preview without exposing the agent API key. Does not write logs or trigger webhooks.

curl

curl -X POST "$BASE_URL/api/verify" \
  -H "Authorization: Bearer $BEHALFID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"agent_xxx","action":"access_data","resource":"gmail.com"}'