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 irreversible 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 |
appointments.read | Read appointments (with the customer's name, email and phone), appointment types and availability |
appointments.write | Create, update, confirm, cancel and complete appointments (the company's automations run along) |
appointments.delete | Delete appointments |
appointments.send | Email appointment messages to customers |
tasks.read | Read tasks, boards and comments |
tasks.write | Create, update, move and complete tasks, and post comments |
tasks.delete | Delete tasks |
work_orders.read | Read work orders, with the customer's name, address and contact details |
work_orders.write | Create and update work orders, and change their status (completing can send a review request) |
work_orders.delete | Delete work orders |
services.read | Read service requests, with the customer's name, address and contact details |
services.write | Create and change service requests, change their status and add photos |
services.delete | Delete service requests |
quotes.read | Read quotes, with their lines, amounts and the customer details on them |
quotes.write | Create and update quotes (drafts only), and accept or reject them on the customer's behalf |
quotes.delete | Delete quotes |
quotes.send | Email quotes to customers |
invoices.read | Read invoices, with their lines, amounts, payments and the customer details on them |
invoices.write | Create invoices (also from a quote) and update them (drafts only), cancel them, record payments, credit them and record a refund |
invoices.delete | Delete draft invoices |
invoices.send | Email invoices to customers and fetch the payment link for the customer |
orders.read | Read webshop orders, with their lines, addresses and the customer's contact details |
orders.write | Change the status of webshop orders (the customer then gets an email), fill in track and trace and post notes |
messages.read | Read conversations and messages from the inbox |
messages.send | Send messages to customers and close conversations |
reviews.read | Read reviews and review requests |
reviews.write | Send review requests to customers (creating a review itself is not possible) |
meta_copilot.read | Read the state and alerts of the Meta co-pilot |
meta_copilot.write | Halt the Meta co-pilot with the emergency stop, accept or dismiss opportunities and approve or reject proposals (configuring the mandate is only possible in the app) |
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.
A scope alone is sometimes not enough: if the endpoint belongs to a feature that is not in your company's plan — such as the pipeline board, quotes, invoices, work orders, the webshop or reviews — you get 403 with the code feature_not_available, and the field feature names the missing feature. Scopes your company cannot use cannot be granted to a key either.
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 the key leaked, choose no overlap: the old one then stops working immediately.
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 18, 2026