Creating API keys

A key is a token stored in PocketBase. Each key is limited to the services you choose and rate-limited. Requests are logged.

1. Create a key

In the admin, open tokens and add a record. Give it a name for the agent that will use it, pick a kind, and choose its scopes. Leave rate_per_min at 60 or set your own. On save, Orb generates the token and shows it once in the reveal field. Copy it then; the field is cleared after ten minutes and the value cannot be shown again.

For several keys at once, bin/mint-tokens.py takes a JSON plan and writes each token to handoff/<name>.token with mode 600 instead of printing it.

Keys look like gw_<8 characters>_<40 characters>; the stored value is their sha256.

2. Choose which services it can read

Scopes are <service>:read for GET, HEAD and OPTIONS, and <service>:write for every method. A scope for a newly added service appears in the form after a sync, because the hook reads the manifests when PocketBase starts.

3. Test it

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:8480/<service>/<endpoint>"

200 with your service’s response means the key works. No token or a malformed one gives 401; the wrong scope, a revoked key, or an expired key gives 403; over the rate limit gives 429.

Keys and agents

Make one key per agent. Revoke a key by ticking revoked on its record; that takes effect on the next request. Set expires if the key should stop on its own.

There is no rotate-in-place button. To rotate, create a new key with the same scopes, give it to the agent, then revoke the old one. Deleting the record also works and removes it from the list. token_events keeps the request history for 90 days.