How do I issue 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 first.

​

Create a key

1. Open API settings

   Go to Settings → API in the Klipy app.

2. 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.

3. 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.

   Screenshot coming soon

   Screenshot coming soon: Settings → API, scope checkboxes and access-level radio

4. 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.

   Screenshot coming soon

   Screenshot coming soon: Key shown once reveal screen with copy button and 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.

​

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 — scopes, access levels, and the envelope format.
• Migrating from v1 — what changed from v1’s key system.