Authentication
How to authenticate with an API key, which scopes exist and how to manage keys safely.
The Authorization header
Send your key with every request as a Bearer token:
GET /api/v1/me HTTP/1.1
Host: app.klantly.com
Authorization: Bearer kly_4fZ2mQ8v...Without a valid key you get 401 with the code unauthenticated or invalid_api_key.
What a key looks like
A key always starts with kly_, followed by 49 characters. The prefix makes a leaked key recognisable, for example to secret scanning on GitHub. The last characters are a checksum: a key with a typo is rejected immediately.
Klantly only stores an encrypted fingerprint of the key. Nobody can show it again later, not even Klantly. Lost it? Create a new one.
Scopes
A key can only do what its scopes allow. When creating a key, choose Read only, Full access or your own selection.
| Scope | Description |
|---|---|
customers.read | Read customers and leads |
customers.write | Create and update customers and leads |
deals.read | Read deals and pipeline stages |
deals.write | Create, update, move and archive deals |
users.read | Read the company's users |
company.read | Read company details |
webhooks.manage | Manage webhook endpoints |
events.read | Retrieve events |
A key never gets more permissions than the administrator who creates, edits or renews it: you cannot grant permissions you do not have yourself. If a scope is missing, you get 403 with the code insufficient_scope, and required_scope names the scope that is needed.
Expiry date, IP allowlist and renewing
- Expiry date: 30, 90 or 365 days, or unlimited. The default is 365 days. In Klantly you can see which keys expire soon.
- IP allowlist: restrict a key to the IP addresses or ranges (CIDR) of your server.
- Renewing: you get a new key with the same settings. The old one can stay valid for 1 hour, 24 hours or 7 days, so your integration can switch over without interruption.
If a key has leaked
- Revoke the key right away under Integrations → API. It stops working immediately.
- Create a new key and put it in your integration.
- Check the Usage tab to see which requests were made with the old key.
Storing keys safely
- Keep keys in an environment variable or a secrets manager, never in your source code.
- Only use a key on a server. The API does not accept requests from a browser (no CORS).
- Give every integration its own key with only the scopes it needs.
Last updated on September 15, 2026