# Keys and rotation

> How a key acts as its maker, how long it lives, what ends it early, and how to rotate keys without stopping your work.

Markdown twin of https://panlytics.net/developers/security/keys (last updated 2026-10-25). Every page of the Panlytics developer docs is listed at https://panlytics.net/developers/llms.txt, and all of them are in one file at https://panlytics.net/developers/llms-full.txt. The site guide is https://panlytics.net/llms.txt.

## What a key is

A key is a long secret that starts with `pan_`. A program sends it in the `Authorization` header of every call:

```http
GET /api/v1/me HTTP/1.1
Host: panlytics.net
Authorization: Bearer pan_...
```

The key acts as the person who made it, in the company it was made in. Every call runs through the same checks the person's own pages use, with the person's role read fresh on each call, and then the fence on top. Whatever the key does is recorded under the person's name and marked as done with a key. In the audit log it reads "name (AI key)".

Panlytics never stores the key itself. It keeps a keyed fingerprint (an HMAC: a hash that also needs a secret only the server holds), so a copy of the database is not a copy of anybody's keys. That is also why the key is shown only once.

## Who may make one

Two things must be true:

1. **Developer mode is on** for the company. The CEO switches it on, on the organisation's Developer page.
2. **The person's role holds "Make keys for programs and AI agents".** The CEO holds it. Only the CEO can put it on another role.

Making a key also needs a **recent sign-in**: if you signed in a while ago, Panlytics asks you to confirm your password or passkey first. A key can never make another key, so a program can never renew its own access.

Each person may hold **five live keys** at once. Revoke one you no longer use to make room for a new one.

## How long a key lives

A key ends **1 to 5 hours** after it is made. The CEO chooses the period for the whole company, and one hour is the default. Shortening the period shortens every live key at once; lengthening it only affects keys made afterwards. No key ever works longer than five hours, whatever the setting says.

The end is a fixed moment, in `key.endsAt` from `GET /v1/me`. Using a key does not extend it.

When a key reaches its end, its maker is told once, in the bell.

## What ends a key early

| What happens | Which keys end |
| --- | --- |
| The maker revokes the key on their Developer page | That key |
| The CEO revokes it from **Every key in the company** | That key |
| The CEO switches developer mode off | Every key in the company |
| The CEO shortens the period | Every key older than the new period |
| The maker is removed from the company | The maker's keys in that company |
| The maker is switched off or banned | Every key the maker holds |
| The maker changes their password and signs out other devices, or signs out everywhere | Every key the maker holds |
| The maker's role loses "Make keys for programs and AI agents", or the maker moves to a role without it | Every key the maker holds in that company, revoked at once |

An ended or revoked key answers `401` with the code `api.key_refused` on every call. It stays on the Developer pages for a week, marked as ended, so you can see when it stopped.

## Rotating keys

Because a key ends within hours, rotation is part of normal work rather than an emergency.

1. Make the new key before you need it. You can hold up to five, so the old and the new can overlap.
2. Switch your program or agent to the new key.
3. Revoke the old key, or let it end on its own.

For a program that runs on a schedule, make the key at the start of each run and let it end afterwards. For an agent, see [When the key ends](https://panlytics.net/developers/connect-an-ai-agent#when-the-key-ends).

> [!WARNING]
> If a key leaks, revoke it at once on your Developer page. A CEO who cannot reach the maker can revoke it from **Every key in the company**, or switch developer mode off to end every key.

## Keeping a key safe

- Put the key in an environment variable or your platform's secret store, never in a file that is committed.
- Never log it, print it or send it in a URL. Panlytics reads it only from the `Authorization` header.
- Give each program and each agent its own key, with a label that says which, so you can revoke one without stopping the others.
- A key starts with `pan_`, which secret scanners look for. If one is found in a repository, revoke it.