Get started
Documentation topics
Developer docs

API keys

Send an agent API key in the Authorization header on the send, read, and media routes:

Authorization: Bearer unpoll_ak_…

Create, list, and revoke keys in the dashboard under the agent's API keys tab.

Scope and storage

  • A key works only for its own agent's send, read, and media routes. It cannot manage keys, connect agents, read event or delivery history, request manual redelivery, or call any other route.
  • A key for a different agent gets the same 404 not_found as an agent that does not exist.
  • Keys are unpoll_ak_ followed by 256 random bits encoded as base64url. Unpoll stores only the key's SHA-256 hash and a 16-character display prefix, not the recoverable key.
  • The complete key is shown only when created. A lost key cannot be shown again; create another.
  • Keep keys on your server. Never ship one in a browser or mobile app, commit it, or print it in logs.

Rotation and revocation

An agent can have up to 10 active keys. To rotate without interrupting requests:

  1. Create a new key.
  2. Deploy it to your server.
  3. Revoke the old key.

Revocation is immediate. Disconnecting an agent revokes all of its keys, and a disconnected agent cannot receive new keys. Repeating a revoke request is harmless.

Key-management routes

These routes use a Firebase ID token from dashboard authentication, not an agent API key. Their base URL is https://api.unpoll.cc.

MethodRouteRequest and result
POST/v1/agents/{id}/api-keys{ "name": "Production bot" } → 201, key view plus the one-time key.
GET/v1/agents/{id}/api-keys{ "api_keys": [...] }, newest first, at most 100 entries, including revoked keys.
DELETE/v1/agents/{id}/api-keys/{key_id}200, key view with revoked_at.

A key view contains id, name, prefix, created_at, nullable last_used_at, and nullable revoked_at. last_used_at is updated at most once a minute.

Creating an eleventh active key returns 409 api_key_limit. See errors for the shared JSON error format and the distinction between API-key and dashboard authentication.