API keys

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 and create one. Or with the CLI:

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

Use a key

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:

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:

Revoking every sign-in with 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 sees every new key.