Skip to main content

API keys

An API key lets a program call your instance: a script, a scheduled job, or a command typed into a terminal. It stands in for signing in, so nothing has to keep your password in a file.

You make keys yourself, from Settings → API keys. Nobody can make one for you, not even an administrator.

What a key can do​

A key carries exactly what you can do, read fresh on every request. If you coordinate two groups, so does your key. If a role is taken away from you, the key loses it at once, with nothing to refresh and nothing to reissue.

What a key cannot touch is your account itself. It cannot make another key, change your password, or end your sessions. Those need you, signed in with your password. It can ask who it is authenticated as, which is how a script checks it is set up correctly.

Making one​

Give the key a name saying what it is for, and choose how long it should last. The name is what you will read later when deciding whether a key is still needed, so nightly backup is worth more than key 2.

The key is shown once. The instance stores only a fingerprint of it, so there is no way to see it again: copy it when it appears, and if it is lost, revoke it and make another.

Using one​

Send it as a bearer credential on every request:

curl -H "Authorization: Bearer kk_your_key_here" https://your-instance/api/v1/auth/me

Every endpoint in the API reference accepts a key in that header, exactly where it accepts a signed-in session.

A refusal comes back as 401 with the code invalid_token. That one code covers every reason a credential does not work: expired, revoked, or never issued. Which of the three it was is not something the API will tell whoever is asking.

Expiry and revoking​

Every key expires. You choose the length when you make it, up to a ceiling the instance sets, and there is no option for a key that lasts forever. A key that outlives the reason it was made is the usual way this goes wrong.

An expired key stays in your list, marked as expired, until the instance's housekeeping removes it. That is deliberate: when a script stops working, the list should be able to tell you why.

Revoking is immediate. The next request presenting that key is refused, with no window to wait out.

For administrators​

The longest life anybody may ask for is set in Administration → Platform, and defaults to a year. Lowering it applies to keys made from then on; keys already issued keep the date they were given.