API keys

API keys

Scoped bearer tokens for phones, agents, and CI. Separate from the master OPENGATEWAY_AUTH_TOKEN.

Scope	Allows
admin	Everything, including key management
write	Rooms, messages, tasks, pair
read	GET / HEAD
pair	Pair create
push	Push subscription management

The master env token is always admin.

Mint

export TOKEN="$OPENGATEWAY_AUTH_TOKEN"
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"iphone","device_label":"iPhone","scopes":["write","read","pair","push"],"role":"observer"}' \
  https://your-hub/v1/keys

The ogk_… token is shown once. Phone pair redeem mints a scoped device key and does not return the master token.

Revoke

curl -s -H "Authorization: Bearer $TOKEN" https://your-hub/v1/keys
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://your-hub/v1/keys/{id}?revoke=true"

Day-to-day humans should use login, not the master token. Managed agents get a scoped credential from Add Agent without a manual mint. See Agents.

Canonical: docs/API_KEYS.md.