---
title: API keys
description: 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](https://my.pols.so/account), 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

```sh
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:

```sh
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](/getting-started/limits/#rate-limits).

## 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](/agents/mcp/).
- Do not put your pols key into a sandbox. Sandboxes cannot reach the pols API anyway.