Prerequisites
- You must have the Admin role in your Klipy workspace.
- Keys are workspace-scoped. A key issued by one workspace cannot access another.
Create a key
Open API settings
Go to Settings → API in the Klipy app.
Name the key
Enter a name that identifies the key’s purpose and owner—for example,
data-warehouse-sync or internal-crm-integration. Names are for your reference only and have no effect on key behavior.Select scopes
Choose the minimum scopes the integration needs. Keys with fewer scopes are easier to audit and limit the blast radius if a key is compromised.
| Scope | Access granted |
|---|---|
ALL | Full read and write access to all resources |
people:read | Read person records |
people:write | Create, update, and upsert person records |
companies:read | Read company records |
companies:write | Create and update company records |
companies:remove | Delete company records |
interactions:read | Read interaction records |
interactions:write | Create interaction records |
Set an expiry date
Choose when the key should expire. Once a key expires, all requests using it return 401. Select No expiry only for long-lived service accounts where key rotation is managed elsewhere.
Use the key
Send the key on every request using one of these methods:klipy_api_. See Introduction for base URL details and response envelope format.
Security practices
- Never commit keys to source control. Use environment variables or a secrets manager.
- Use the narrowest scopes needed. A key for a read-only sync job does not need
writescopes. - Set expiry dates. Prefer short-lived keys over permanent ones for external integrations.
- One key per integration. Sharing keys across systems makes rotation and auditing harder.
- Revoke immediately on compromise. If a key is exposed, revoke it before rotating.
Revoke a key
Go to Settings → API, find the key in the list, and click Revoke. The key becomes invalid immediately. Any in-flight requests using the revoked key return 401. There is no way to re-activate a revoked key. Issue a new key and update your integration.Related topics
- Introduction — Base URL, response format, scopes, and rate limits.
- Authenticate API key — Endpoint to verify a key and return workspace info.