API Keys

Personal and organization API keys: creating a key, seeing its secret once, and revoking access.

Settings → API keys (/settings/api-keys) lets a signed-in user create personal API keys for their own scripts and tools. The page stays available when API_ACCESS_KEYS is off (Customer API Access): creation is hidden and refused, while existing keys can still be listed and revoked.

Creating a Key

The form asks for:

  • Name (1 to 32 characters), to tell keys apart later.

  • Scopes: the personal scopes of your scope catalogue (apiAccessScopes in apps/web/config/api-access.config.server.ts), each a checkbox. At least one is needed. With none configured, the page says there's nothing to grant instead of showing the form.

  • Expires: never (the default) or in 7, 30, 90 or 365 days. While "never" is picked, the form explains that such a key works until it's revoked.

  • The key always belongs to the signed-in user. The server ignores owner fields in the request.

  • Creating a key needs a sign-in from the last 10 minutes (Sessions and Guards). A stale session gets "sign in again" and comes back to the page.

  • Creating a key is refused while impersonating.

The Secret, Once

After a successful create the page shows the secret with a copy button, its identifier (the prefix and next 6 characters, safe to keep in notes) and its expiry.

The secret travels only in that create response: the page's GET loader never returns it. A reload, a back navigation or "I've saved it" shows the form again and the secret is gone.

Nobody can recover a lost secret. If you lose one, revoke the key and create a new one.

Revoke a Key

Your keys lists only your personal keys: name, safe identifier, expiry and status. Choose Revoke, then confirm.

  • Revocation needs a valid session but no recent sign-in.
  • After it, requests that use the key fail; already authorized work may finish.
  • Repeating a revocation is safe.
  • Keys belonging to another user or an organization cannot be listed or revoked here.
  • Revocation reads your keys straight from the database, so it works even with API_ACCESS_KEYS off.
  • Secrets and hashes never appear in the list.

Replace a Key

Use the existing create and revoke controls in the personal or organization API keys page:

  1. If asked, sign in again. Then Create key with the scopes your integration needs. Give it a distinct name so you can identify the old and new keys.
  2. Copy and store the new secret. Update your integration to use it, then confirm the integration's requests succeed.
  3. Revoke the original key and confirm. Requests using the new key continue working.
  • The old key keeps working until you revoke it or it expires.
  • Both keys count toward the owner's limit of 20 active keys (apiAccessLimits.maxActiveKeys). At the cap, revoke an unused key first.
  • If you lose the new secret before saving it, revoke that key by its name and create another. The old key is unaffected.
  • An organization replacement can carry only scopes the creating member can grant today.

Organization Keys

The organization's Settings → API keys (/settings/organization-api-keys) manages the active organization's keys. Each action has its own permission:

PermissionAllows
apiKey: readListing safe metadata
apiKey: createCreating a key
apiKey: deleteRevoking a key, including keys issued by another member

The default owner and admin roles have all three. Members without any of them cannot open the page.

Creating:

  • The form offers only organization scopes the member can grant today. The shipped account:read scope requires apiKey: read; customize its organization statement in your scope catalogue.
  • Creating a key needs a recent sign-in and refuses impersonation.
  • The secret appears only in that create response, even for a role that can create but cannot list keys. Reloading or choosing I've saved it removes it permanently.

Afterwards:

  • Organization keys retain their granted scopes when the issuing member leaves or changes role.
  • Revocation needs current apiKey: delete permission, without a recent sign-in.
  • Listing and revoking still work with API_ACCESS_KEYS off.
  • If you switch organizations in another tab, a form opened for the previous organization is refused and asks you to reload. It never changes the newly active organization's keys.

Use a Key

Send the secret in the x-api-key header, never in a URL. Keys reach the app's MCP server (Connecting Clients) and any route the app protects with them (API Keys in Your Routes).

Files

FileOwnerWhat
apps/web/pages/(app)/settings/api-keys.tsx, api-keys.server.tsyouPersonal page, loader and create/revoke actions
apps/web/pages/(app)/settings/organization-api-keys.tsx, organization-api-keys.server.tsyouOrganization page, independent permission checks and create/revoke actions
apps/web/components/api-key-create-form.tsx, api-key-issued.tsxyouThe form and the one-time secret card
apps/web/lib/api-access.server.tskitapiAccessFor(c) (acts as the session's user, maps refusals), requireApiKeys, the one-time hand-off
apps/web/config/api-access.server.tskitBinds @kit/api-access to the app's auth and scopes
apps/web/config/api-access.config.server.tsyouThe switches and the scope catalogue