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 (
apiAccessScopesinapps/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_KEYSoff. - 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:
- 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.
- Copy and store the new secret. Update your integration to use it, then confirm the integration's requests succeed.
- 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:
| Permission | Allows |
|---|---|
apiKey: read | Listing safe metadata |
apiKey: create | Creating a key |
apiKey: delete | Revoking 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:readscope requiresapiKey: 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: deletepermission, without a recent sign-in. - Listing and revoking still work with
API_ACCESS_KEYSoff. - 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
| File | Owner | What |
|---|---|---|
apps/web/pages/(app)/settings/api-keys.tsx, api-keys.server.ts | you | Personal page, loader and create/revoke actions |
apps/web/pages/(app)/settings/organization-api-keys.tsx, organization-api-keys.server.ts | you | Organization page, independent permission checks and create/revoke actions |
apps/web/components/api-key-create-form.tsx, api-key-issued.tsx | you | The form and the one-time secret card |
apps/web/lib/api-access.server.ts | kit | apiAccessFor(c) (acts as the session's user, maps refusals), requireApiKeys, the one-time hand-off |
apps/web/config/api-access.server.ts | kit | Binds @kit/api-access to the app's auth and scopes |
apps/web/config/api-access.config.server.ts | you | The switches and the scope catalogue |