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

# Issuing API keys

> Create, scope, rotate, and revoke v2 API keys.

v2 API keys work differently from v1 keys. Where a v1 key was a Convex document ID, a v2 key is a real secret: a random value that Klipy stores only as a hash, never in plaintext. If you're migrating an existing integration, see [Migrating from v1](/api/v2/migrating-from-v1) first.

## Create a key

<Steps>
  <Step title="Open API settings">
    Go to **[Settings → API](https://app.klipy.ai/settings/api)** in the Klipy app.
  </Step>

  <Step title="Choose scopes">
    Select exactly the scopes the integration needs, for example `contacts:read` and `deals:write`. There is no `ALL` scope — a key can only do what it's explicitly granted.
  </Step>

  <Step title="Choose an access level">
    * **Organization-wide** — reads and writes any record in the organization. Use this for server-to-server integrations acting on behalf of the whole team.
    * **User-bound** — scoped to one user's own records. Use this when the integration should only ever see what that specific user can see.
  </Step>

  <Step title="Copy the key">
    The full key (`klipy_live_...`) is shown **once**, immediately after creation. Store it in your secrets manager or environment variables — Klipy cannot show it to you again. If you lose it, rotate the key to issue a new one.
  </Step>
</Steps>

<Warning>
  Treat a v2 key exactly like a password. Anyone holding it can act within its scopes and access level. Never commit it to source control or embed it in client-side code.
</Warning>

## Rotate a key

Rotating a key issues a new secret on the same key record — the scopes and access level are preserved, only the secret changes.

The previous secret keeps working for a short grace window after rotation, so you can update a running integration without downtime: deploy the new key, confirm it works, then the old one stops resolving once the grace window ends.

## Revoke a key

Revoking a key immediately stops it from authenticating — any request using it returns `401`. The key record itself is kept (not deleted) so past API activity remains attributable in your audit history.

## Key lifecycle summary

| State     | Behavior                                                                    |
| --------- | --------------------------------------------------------------------------- |
| `active`  | Authenticates normally.                                                     |
| Rotated   | Old secret works until the grace window ends; new secret works immediately. |
| `expired` | If the key has an expiry set and it has passed, requests return `401`.      |
| `revoked` | Requests return `401`. Cannot be reactivated — issue a new key instead.     |

## Related topics

* [Introduction](/api/v2/introduction) — scopes, access levels, and the envelope format.
* [Migrating from v1](/api/v2/migrating-from-v1) — what changed from v1's key system.