API keys

An API key is what an external service presents to prove it is allowed to work on your project. Each key has a name you choose, a status, the set of permissions it was granted, an expiry, and a full value that is shown only once. From the API Access tab of a project you create a key — deciding as you go what it may reach and how long it lasts — read the list of the ones already there, rename or disable one, and delete one you no longer want.

Before you start — Creating, editing and deleting keys is reserved to a project's administrators. Another member opens the tab and reads the list, but has no Create an API key button and no Detail button on any row — and the pages behind them send them back.

Note — Creating, editing and deleting all happen in a panel that slides in from the right, over the list. The panel carries the action's title, a close (✕) button and a View full page link at the bottom. The outcome is written in the panel — you're never sent to another page. Closing it — with ✕, by clicking the greyed-out area beside it, or by pressing Esc — refreshes the list behind so it shows what you just did.

Create an API key

The full key exists in readable form for one page view only. Plan to copy it before you start.

1. Open your project, then the API Access tab.
2. Click Create an API key — the button above the list, or the one in the

No API access panel if this is your first key.

1. On Create an API key, enter a Name. It's for you to tell your keys

apart, as the helper line suggests: Example: Production, test, integration. Up to 200 characters.

1. Open Access and choose Full access or Restricted access. The

helper line states the difference: Full access grants every route, now and in the future. Restricted access grants only the permissions you pick.

1. If you chose Restricted access, fill in the Permissions box that

appears under the field. It has one line per part of the API your project serves, each labelled with that part's name (product, category…), and each line offers No access, Read, Read and write and Write. Leave a line on No access to keep the key out of it.

1. Open Expiry and choose 30 days, 90 days, 365 days or **Never

expires**.

1. Click Next.
2. The API key has been created. appears in the panel. Close it.
3. The list behind refreshes with the new key at the top, its full value in a

read-only box under its name. Copy it now.

An email confirming that a key was created is sent to you.

Important — copy this key now, it will not be shown again. is printed in red under the box, and it's literal: leaving the list or reloading it replaces the full value with a preview like sk-project-...a1b2, and nothing brings the full key back. If you lose it, delete the key and create another.

Note — A key with no name is refused with The API key name is required. — the panel stays open with what you typed.

Note — Name takes up to 200 characters and the field stops you there. The limit counts characters, not bytes, so an accented or non-Latin name gets the full 200 and is stored exactly as you typed it. A longer value that reaches the server anyway is refused with Please use at most 200 characters. in red, and no key is created.

Note — The Permissions box only appears once Access is on Restricted access; on Full access the key reaches everything and there is nothing to pick. The lines it offers are the parts of the API your project serves, so two projects can show different ones.

Note — Read and write on a line grants every action on that part of the API, including ones added later. Read and Write each grant only themselves: a key set to Write can't read.

Important — Access, Permissions and Expiry are chosen once, when the key is created. The Detail panel shows them but can't change them. To widen, narrow or extend a key, create a new one and delete the old one.

Tip — The help box beside the form makes the case under Permissions and expiry: Grant only the permissions the integration needs, and set an expiry so a leaked key stops working on its own. Expiry adds its own warning — A key that never expires can only be retired by deleting it. Prefer a duration you can plan a rotation around.

Note — Leaving Access or Expiry unset is refused with Choose an access level for this key. or Choose an expiry for this key., and choosing Restricted access without granting a single line is refused with A restricted key needs at least one permission, otherwise every route refuses it. The panel stays open with what you entered and no key is created.

Read your project's keys

1. Open your project, then the API Access tab.
2. Read the list — one row per key, with these columns:

• API key — the name you gave it, then its value. That's the full value

just after creation, and a preview of the last four characters from then on.

• Status — Activated for a key that works, Suspended for one that

has been turned off. The Detail panel calls that same state Disabled.

• Permissions — Full access, or, for a restricted key, one permission

per line written the way the API reads it: product:read, category:write, product:* for read and write.

• Expiry — Never, or the date the key stops working, followed by

(Expired) once that date has passed.

• Created by — the email address of the person who created it.
• Created on — the date and time it was created.

1. Use the pagination buttons (Previous / Next) to browse a long list.

The counter beside them reads the rows you're on and the total, as 1-50 | 63.

The line under the list — API keys let you connect an external service to this project. — is a reminder, not a link.

Note — A brand-new key reads New on the one view that shows its full value, then Activated from the next view on.

Note — A project with no key at all shows No API access and No API key has been created on this project. in place of the list.

Note — Deleted keys are gone from the list for good; there's no filter or archive that brings them back.

Important — Reaching its expiry doesn't change a key's Status: the row still reads Activated, with (Expired) beside the date. Calls signed with it are refused all the same. The Expiry column is where you see the date coming, so check it and create the replacement key before it lands.

Rename a key or disable it

Disabling is the reversible way to stop a key: it stays on the list and you can turn it back on.

1. Open the API Access tab, then click Detail on the key's row. The

Detail panel opens on API key details.

1. Change the Name, or set Status to Active or Disabled.
2. Click Save.

You'll see The API key has been updated. Close the panel and the row shows the new name and status.

Important — Disabling a key blocks every call that uses it, straight away. Anything that was signing its requests with that key stops working until you set it back to Active.

Note — Name here obeys the same 200-character limit as the creation panel, counted the same way, and the name you type is stored whole. Over the limit, Save does nothing and Please use at most 200 characters. appears in red — the status you picked isn't saved either, so shorten the name and click Save again.

Note — The rest of the panel is read-only: the API key preview, the Permissions the key was granted, its Expiry, the User who created the key, the Created date and Last used, the last time a call presented it. Last used stays empty for a key nothing has called yet.

Note — Permissions here reads Full access, or the same permission lines as the list (product:read, category:*…). Expiry reads Never expires, or the date and time the key ends, followed by (Expired) once it has passed. Neither can be edited: to change what a key may reach or how long it lasts, create a replacement and delete this one.

Delete a key

Deleting is permanent. Disable the key first if you only want to stop it for a while.

1. Open the API Access tab, then click Detail on the key's row.
2. Scroll to the grey box at the bottom, headed Delete this API key. —

it warns The key will no longer be usable.

1. Click Delete.
2. Close the panel.

The API key has been deleted. appears in the panel and both the Save and the Delete buttons disappear, so nothing can be done to the key any more. The list behind refreshes without it, and an email is sent to whoever created the key.