Authentication

Every request to the REST API and the MCP server authenticates with your Agent API Token, passed as a Bearer token:

Authorization: Bearer okm_<your-token-here>

Your token starts with okm_. The same token works for both the REST API and the MCP server.

Scopes: read vs full

Tokens come in two scopes:

Every endpoint in the REST API requires a full-scope token. A read-scope token is rejected on every route with:

{ "error": "insufficient_scope", "message": "This endpoint requires a full-scope token." }

with HTTP status 403. This API touches worker data and reaches workers directly, which is outside what a read token is meant for.

Getting a token

OnKey staff issue and scope tokens from the Admin Portal — you can't self-serve one. If you don't have a token, or aren't sure which scope yours is, reply to your Virtual Operations Agent email and ask. Your Virtual Operations Agent will route the request to OnKey staff.

Keeping your token safe

• Keep the token out of client-side code, version control, and shared documents.
• Treat it like a password — anyone with it can act as your agent.
• If it's ever exposed, tell OnKey staff and we'll revoke it immediately.

A human still approves anything sent through an AI assistant — the REST API is different

The MCP connection (Claude, ChatGPT, and similar) always shows an Admin a preview of any message, alert, or reminder before it sends — the "stage → confirm" safety step, because an AI assistant can misread an instruction.

The REST API skips that step and sends immediately. That's intentional: if you're calling the REST API, a developer on your team wrote the exact request being sent — there's no AI in the loop that could hallucinate a recipient list or misquote a message. The developer who wrote the integration is the approver. Build your own review step into your software if you want one before calling POST /messages or POST /alerts.