> Documentation index: https://docs.kiste.run/llms.txt, a list of every page in this documentation.

# API keys

> Create labelled, expiring API keys for CI, scripts and agents, use them, revoke them, and what they can't do.

An API key lets a script, a CI job or an agent use Kiste without a browser. It
starts with `ksta_`, has a label and a fixed expiry, and can be revoked at any
time.

## Create a key

In the console, open [API keys](https://console.kiste.run/app/api-keys) and
create one. Or with the CLI:

```bash
kiste auth token create ci-github --expires-in 2592000   # 30 days, the default
kiste auth token list
kiste auth token revoke KEY_ID
```

The key is shown **once**, when you create it. Kiste stores only a hash, so it
can't show it again; copy it into your secret store right away. The list shows
each key's label, a short non-secret hint, when it was created, when it expires
and when it was last used.

- **Lifetime:** from 5 minutes to 1 year (`--expires-in` in seconds). Choose
  the shortest that works.
- **Labels** are unique among your active keys.
- **At most 10** active keys per account ([L08](https://docs.kiste.run/errors/l.md#l08)).

## Use a key

```bash
export KISTE_TOKEN=ksta_...
kiste list
```

The CLI uses `KISTE_TOKEN` instead of its saved sign-in.
`kiste login --with-token < key.txt` saves a key as the CLI's sign-in on a
headless computer. For the HTTP API, send it as a bearer token:

```bash
curl -sS https://kiste.run/v1/instances -H "Authorization: Bearer $KISTE_TOKEN"
```

## What an API key can't do

An API key can do everything with your Kisten that you can, but not change who
you are or how you pay:

| An API key can't | Code |
| --- | --- |
| Create other API keys | [A11](https://docs.kiste.run/errors/a.md#a11) |
| Start a payment or change billing settings (checkout, credit, auto-refill, the payment portal) | [B17](https://docs.kiste.run/errors/b.md#b17) |
| Delete the account | [A30](https://docs.kiste.run/errors/a.md#a30) |

Revoking every sign-in with [sign out everywhere](https://docs.kiste.run/account/sessions.md#sign-out-everywhere)
leaves API keys valid; revoke them here.

## Revoke a key

Revoke a key in the console or with `kiste auth token revoke KEY_ID`. Any
process still using it gets `401` at once. A key that signs out with
`kiste logout` while it is the CLI's sign-in is revoked as well.

## Keeping keys safe

- Store keys in your CI's secret store, never in a repository.
- Give each job or agent its own key with a clear label, so you can revoke one
  without touching the others.
- Prefer short lifetimes and create keys as part of the job when you can.
- Creating a key raises an `api_token.created` event, so a watcher of your
  [event stream](https://docs.kiste.run/kisten/automation.md#follow-the-event-stream) sees every new key.

## Related topics

- [Overview](https://docs.kiste.run/account.md)
- [Sign-in and sessions](https://docs.kiste.run/account/sessions.md)
- [Webhooks and alerts](https://docs.kiste.run/account/webhooks-alerts.md)
- [Plans and billing](https://docs.kiste.run/account/billing.md)
- [Export your data](https://docs.kiste.run/account/data-export.md)
- [Delete your account](https://docs.kiste.run/account/delete-account.md)
- Previous: [Sign-in and sessions](https://docs.kiste.run/account/sessions.md)
- Next: [Webhooks and alerts](https://docs.kiste.run/account/webhooks-alerts.md)