API keys
A management API key lets a script or an external system call the management API without a user session. It authenticates as a service principal: organization-scoped, carrying an explicit permission set, and never eligible for the platform-superadmin bypass.
Present it in the X-Polyant-Key header. Most management routes accept it as an alternative to a session cookie or bearer token — the REST API reference states which auth each route takes.
Do not confuse it with the two per-agent keys: the auth API key that guards
/v1/chat/completions, and the HTTP channel key. Those authenticate traffic to one agent; a management key administers the organization.
Administering keys
Enterprise feature. The API-keys screen and its multi-key, scoped surface require the granular-API-keys feature. Without it a deployment has a single fixed key, seeded out of band, and this screen is unreachable.
The API keys screen (/api-keys) requires org:write — only Owners administer keys. The endpoints carry a dedicated 30 requests/minute limit.
Creating a key takes:
- Name — required, up to 255 characters.
- Permissions — any subset of the Owner permission matrix. The picker is rendered from
GET .../api-keys/permissions, which returns exactly that ceiling, and the API rejects anything outside it: a key can never out-scope an Owner. Omit the field and the key gets the full Owner set. - Expiry — optional ISO date, and it must be in the future. A past or invalid date is refused rather than creating a key that is already dead.
The plaintext token is returned once, at creation, in the form pk_<id>_<secret>. Only a hash is stored. Copy it then; there is no way to see it again.
The <id> half is public and selects the row; the secret half is 32 random bytes. Handing out the id alone gives nothing away.
Editing and rotating
Name, permissions, and expiry are editable. The secret is not — there is no rotate operation by design. To rotate, create a new key, switch the caller over, then delete the old one.
Deleting a key takes effect immediately; any caller still presenting it starts failing authentication.
Choosing permissions
Give a key the narrowest set that does its job, because a key is a bearer credential with no second factor and no session expiry beyond the date you set. Some concrete examples:
| The key does | Give it |
|---|---|
| Reads analytics for a dashboard | analytics:read |
| Exports conversations for a warehouse | conversation:read |
| Provisions agents from CI | agent:read, agent:write, agent.prompt:write, agent.tool:write |
| Manages the shared skill catalogue | skill.catalog:read, skill.catalog:write |
Note what the last two cases pointedly do not include: agent.secret:read and agent.export:read reveal which secrets an agent holds, so keep them off any key that does not genuinely need them.
See Roles and permissions for the full taxonomy.
See also
- Roles and permissions
- Authentication — the session-based alternative.
- REST API reference — per-route auth and permissions.