Skip to main content
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.
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.
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

StateBehavior
activeAuthenticates normally.
RotatedOld secret works until the grace window ends; new secret works immediately.
expiredIf the key has an expiry set and it has passed, requests return 401.
revokedRequests return 401. Cannot be reactivated — issue a new key instead.
Last modified on July 7, 2026