> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keebai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get an API key

> Create, list, and revoke Personal Access Tokens from the Keebai dashboard. Scoped permissions, instant revocation, dev mode unlocked per role.

Keebai API keys are **Personal Access Tokens (PATs)**: each user mints their own, with explicit scopes, revocable at any time. A token always acts with the identity of the user who created it.

## Unlock developer mode

You need the `developer.manage_tokens` permission to see and manage tokens. It's a new permission that a tenant admin has to grant you:

<Steps>
  <Step title="Ask an admin">
    They go to **System Settings → Roles**, open your role, check **Manage API Tokens** under *Developer*, and save.
  </Step>

  <Step title="Refresh your session">
    Log out and back in so the UI picks up the new permissions. You'll see the **Developer API** banner at the bottom of System Settings.
  </Step>
</Steps>

## Create a token

<Steps>
  <Step title="Open API Keys">
    Go to **System Settings**. Scroll to the *Developer API* banner and click **Open API Keys**. Direct URL: [app.keebai.com/system-settings/api-keys](https://app.keebai.com/system-settings/api-keys).
  </Step>

  <Step title="Click Create API Key">
    A modal opens with three fields.
  </Step>

  <Step title="Name it">
    Give the token a descriptive name. It saves you headaches later when you have many active tokens. Examples: `Zapier production`, `n8n nightly sync`, `Local dev`.
  </Step>

  <Step title="Pick the scopes">
    Check only the permissions the token actually needs. Only the permissions your own user has are shown.

    <Tip>
      Least privilege wins. If your integration only reads messages, don't grant write permissions. The tighter the scope, the smaller the blast radius if the token leaks.
    </Tip>
  </Step>

  <Step title="Set expiration (optional)">
    We recommend 90 days. After that date the token stops working and you mint a new one. Leave it blank for no expiration.
  </Step>

  <Step title="Confirm and copy">
    Click **Create token**. Keebai shows the token **once**, with a **Copy token** button. Paste it into your secret manager before closing the modal.

    <Warning>
      This is the only time you'll see the full token. If you lose it, revoke and create a new one.
    </Warning>
  </Step>
</Steps>

## Token anatomy

Tokens look like this:

```
kbai_pk_a1b2c3d4e5f6...0123456789abcdef
```

* **`kbai_pk_` prefix** — identifies the Keebai format. Secret-scanning tools (GitHub secret scanning, gitleaks) recognize it automatically if the token ever lands in a public repo.
* **64 hex chars** — 32 bytes of entropy (256 bits). Not predictable.

After creation, you only see the prefix and the first 4 chars; the rest is hashed server-side.

## List and audit your tokens

The **API Keys** table shows every token you've created (active and revoked):

| Column        | Meaning                                                                              |
| ------------- | ------------------------------------------------------------------------------------ |
| **Name**      | Whatever you typed at creation.                                                      |
| **Prefix**    | First 12 chars (`kbai_pk_a1b2`). Lets you ID it without exposing the secret.         |
| **Scopes**    | Permissions assigned to the token.                                                   |
| **Last used** | Timestamp of the last successful request. Helps spot abandoned or suspicious tokens. |
| **Expires**   | Expiration date, or *Never* if not set.                                              |
| **Status**    | `Active`, `Expired`, or `Revoked`.                                                   |

## Revoke a token

If you suspect a leak, or you don't need the token anymore:

<Steps>
  <Step title="Find the row">
    Look it up by name or prefix.
  </Step>

  <Step title="Click Revoke">
    In the last column, click **Revoke**. Confirm in the dialog.
  </Step>

  <Step title="Verify">
    The token stops working **immediately** — any further request with it returns `401 Unauthorized`. The row stays in the table with status `Revoked` for audit; it isn't deleted.
  </Step>
</Steps>

## Best practices

* **One token per integration.** Zapier + a local script + an internal cron? Three separate tokens. If one leaks, revoke just that one.
* **Rotate every 90 days.** Even without an incident — mint the new one, update integrations, revoke the old.
* **Never on the client.** These tokens are backend-to-backend. Don't ship them inside a mobile app, a public SPA, or anything a user can inspect.
* **Proper storage.** Secrets managers (AWS Secrets Manager, 1Password, GitHub Actions secrets, Vault) — never config files committed to the repo.
* **Watch *Last used*.** Token marked unused for months? Revoke it. Token active outside of expected hours? Investigate.

## Limits

* Up to **10 active tokens per user**. Hit the limit? Revoke one before creating a new one. Need more? Email [support@keebai.com](mailto:support@keebai.com).
* Revoked tokens don't count toward the limit.