Skip to content
pols.so docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

API keys

Create, use, expire and revoke the org API keys that the CLI, the MCP server, the clients and the REST API authenticate with.

Every call to the pols API is made with an API key of your org. The CLI, the MCP server, the TypeScript client and your own scripts all use one.

Creating and revoking keys

Keys are managed only on your account page, where you log in with your email address. An API key cannot create or revoke keys: POST /v1/api-keys and DELETE /v1/api-keys/{key} always answer 403 forbidden. A leaked key therefore can neither create successors for itself nor lock out your other keys.

On the account page you can:

  • Create a key with a name, and let it expire after 30, 90 or 365 days, or never. Its secret (pols_...) is shown once; copy it before you leave the page.
  • See every key with who created it, when it was last used and when it expires.
  • Revoke a key. It stops working at once, and so do the port sessions, desktop links and browser URLs it created.

Your org may have up to 25 active keys; revoked and expired keys do not count. With an API key you can list your org’s keys (GET /v1/api-keys, never with secrets) to check their names, start and expiry.

pols stores only a SHA-256 hash of each key, so a lost key cannot be shown again: create a new one and revoke the old one.

Using a key

With the CLI

pols login                    # paste the key; it is checked and stored
export POLS_API_KEY=pols_...  # or set it per shell; this wins over a stored key
pols logout                   # forget the stored key

pols login reads the key from standard input, never from a flag, so it does not end up in your shell history: echo "$KEY" | pols login works in scripts. The key is stored in your user config directory with permissions that only you can read.

A stored key is only sent to the API address it was stored for (https://api.pols.so by default). To use another address, pass --api-url to pols login, or set POLS_API_KEY together with POLS_API_URL. The CLI refuses plain http:// addresses other than localhost.

With the REST API

Send the key as a bearer token:

curl -H "Authorization: Bearer $POLS_API_KEY" https://api.pols.so/v1/org

A missing, wrong, revoked or expired key gets 401 unauthorized. Repeated failures from one address are rate limited.

Keeping keys safe

  • Give each machine, CI system or agent its own key, so you can revoke one without touching the others, and let keys expire where you can.
  • Pass keys to MCP clients through an environment variable reference or pols login, never as a literal value in a config file; see MCP server.
  • Do not put your pols key into a sandbox. Sandboxes cannot reach the pols API anyway.