# Create & manage keys

> Mint an organization API key in Settings → API keys — name, scopes, optional expiry and IP allowlist — copy the one-time secret, and revoke keys you no longer need. Requires the org:api_keys permission.

Organization API keys are created and revoked in **Settings → API keys**. Both actions require the **`org:api_keys`** RBAC permission (held only by org admins) plus CSRF protection, and every mint and revoke is **audited**.

## Create a key

In **Settings → API keys → Create**, provide:

| Field | Required | Notes |
|---|---|---|
| **Name** | ✓ | A label to recognise the key later (e.g. "Nightly sync", "Partner SDK"). |
| **Scopes** | ✓ | The least-privilege [`org:*` scopes](/docs/oauth/scopes/) this key needs: `org:passes:read`, `org:passes:write`, `org:facilities:read`. |
| **Expiry** |  | Optional date after which the key stops working. Prefer setting one. |
| **IP allowlist** |  | Optional list of source IPs; requests from any other address are rejected. |

Grant only the scopes the integration actually uses. A data-export job needs `org:passes:read`; it does not need `org:passes:write`.

## Copy the secret — it's shown once

On creation the full key is returned **exactly once**:

```
eb_sk_live_9f1c2ab34cd56ef7a8b9c0d1e2f3a4b5
```

Copy it immediately into your secret manager. EntryBit stores only a [SHA-256 hash](/docs/api-keys/overview/) and **cannot show the key again** — if you lose it, revoke it and mint a replacement. Never commit a key to source control, paste it into a client app, or log it.

## Revoke a key

In **Settings → API keys**, revoke any key you no longer trust or need. Revocation takes effect immediately: the next request using that key is rejected with `401`. Revoke a key the moment it may have leaked, a teammate with access leaves, or an integration is retired.

Because minting and revoking both require `org:api_keys` + CSRF and are audited, you get an accountable trail of who created and killed each key.

## Rotation

To rotate without downtime:

1. **Mint** a new key with the same scopes.
2. **Deploy** it to your server / secret manager.
3. **Verify** traffic is flowing on the new key.
4. **Revoke** the old key.

Setting an **expiry** at creation turns rotation into a scheduled habit rather than an afterthought.

## Using the key

Once you have the secret, see [Authenticating requests](/docs/api-keys/authenticating/) for how to send it, and the [Organization API](/docs/api-reference/organization/) for the endpoints it can call.

> This page is about **API keys** (server secrets). Registering an app that signs *users* in is a different task — see [Register an app](/docs/oauth/register-an-app/) under **Settings → Team → OAuth apps**.