# API Keys

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

*Canonical: https://makerkit.dev/docs/void-cloudflare/account/api-keys*

---

**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](../authentication/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](../authentication/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:

| 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: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](../mcp-server/connecting-clients#connect-with-an-api-key)) and any route the app protects with them ([API Keys in Your Routes](../mcp-server/api-keys)).

## 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 |
