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-admin 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.

Nor with a personal API token (pat_), which rides the same X-Polyant-Key header and is told apart by its prefix. That one authenticates a person, reading their live permissions, so it dies with their access. A key is what an automation should hold, precisely because it outlives whoever created it.

A key is bound to its own organization on every route shape - the one it was issued for. Presenting a key for organization A against /api/organizations/B/… is refused, and unlike a human caller a key can never be a member of a second organization: its organization is its entire authority.

One route is deliberately reachable by a key and only by a key: GET /api/service-context, which reports the key’s own organization and permission set. Gating self-introspection on a grantable permission would fail for exactly the narrowly scoped key that most needs to read its own scope.

Administering keys

On the open-source build an organization Owner issues and revokes keys from API keys in the sidebar’s Management group, at /organizations/{org}/api-keys. The page lists each key with its creation date, last use and expiry. Every role sees the entry; for anyone but an Owner the page explains the refusal. The endpoints (GET, POST /api/organizations/{orgSlug}/api-keys and DELETE /api/organizations/{orgSlug}/api-keys/{keyId}) require org:write and carry a dedicated 30 requests/minute limit.

Creating a key takes:

• Name - required, a reminder of what uses it, for example CI or a laptop.
• Expiry - optional, and it must be in the future. Leave it empty for a key that works until it is revoked.

On the open-source build a key always carries the Owner permission set of its organization.

The plaintext token is returned once, at creation, in the form pk_<id>_<secret>. Only a SHA-256 digest of the secret is stored. Copy it then; there is no way to see it again.

A request authenticated with a key can list its organization’s keys but never issue or revoke one, so a leaked key cannot mint its successor. Issuing and revoking a key each write a management audit row.

Managed services. With Polyant managed services the API keys screen lives in Settings → Organization, at /organizations/{org}/settings/organization/api-keys, and requires the granular-API-keys feature. It adds a Permissions picker: any subset of the Owner permission matrix, rendered from GET .../api-keys/permissions, which returns exactly that ceiling. The API rejects anything outside it, so a key can never out-scope an Owner; omit the field and the key gets the full Owner set. Name, permissions and expiry stay editable from a signed-in session. A management key cannot create or edit keys, and it can revoke only itself.

A platform admin can create a key in any organization, with the full Owner matrix, and the key outlives the flag. A key row carries its organization and its permission set and records nothing about who issued it, so removing someone’s platform-admin flag leaves every key they minted working. Auditing an installation after a revocation means walking each organization’s key list and deleting what that person created.

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

The secret cannot be changed: there is no rotate operation, by design. To rotate, create a new key, switch the caller over, then revoke the old one. With managed services the name, permissions and expiry are editable.

Revoking a key takes effect immediately; any caller still presenting it starts failing authentication. This is the only way a key stops working early - no role change, anywhere, revokes one.

Choosing permissions

With managed services, 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:

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.

On the open-source build there is no picker: every key is an Owner key, so store it where you would store an Owner’s password, give it an expiry when the job is temporary, and revoke it when the job ends.

See Roles and permissions for the full taxonomy.

Using a key with polyant-cli

polyant-cli is the command-line client of the management API, and it authenticates with a management key on X-Polyant-Key. Version 0.9.0 is the release that matches Polyant 1.2.0; it is published under Apache-2.0 and needs Node.js 20 or newer. There is no npm registry package: install it from the GitHub release.

On your PATH, for every project:

npm install -g https://github.com/polyant-ai/polyant-cli/releases/download/v0.9.0/polyant-ai-cli-0.9.0.tgz
polyant-cli --version

Pinned in one project, so the CLI follows the API version of the instance that project talks to:

npm install -D git+https://github.com/polyant-ai/polyant-cli.git#v0.9.0
npx polyant-cli --version

Then issue a key as described above and hand it to the CLI through an environment variable, never in a file you commit. With no configuration file the CLI reads POLYANT_URL and POLYANT_KEY:

export POLYANT_URL=https://your-host
export POLYANT_KEY=pk_...
polyant-cli whoami

A project that talks to several instances declares them in a polyant.yaml in the directory the CLI runs from; each target names its baseUrl and, in keyEnv, the name of the environment variable holding its key. The CLI’s README  lists the commands and which of them work against an open-source engine. A personal API token works in the same variable when a script should act on a person’s own authority.

See also

• Roles and permissions
• Authentication - the session-based alternative.
• REST API reference - per-route auth and permissions.