Authentication and scopes

Every request to the Developer API is authenticated with an organization API key sent as a Bearer token. A key carries a fixed set of scopes, and an endpoint answers only when the key holds the scope that endpoint needs.

Send the key as a Bearer token

Send Authorization: Bearer dk_live_... on every request. The key identifies the organization, so there is no organization slug in the URL and no login step. A key can have an expiry date and can be revoked at any time. Dakoty stores only a fingerprint of the key, so a lost key cannot be shown again and has to be replaced.

curl -sS https://api.dakoty.com/api/v1/public/leads \
  -H "Authorization: Bearer $DAKOTY_API_KEY"

Authentication and access errors

A missing, malformed, expired or revoked key returns 401 UNAUTHORIZED. A key that lacks the scope of the endpoint returns 403 FORBIDDEN, and the message names the missing scope. A lapsed organization subscription returns 402 PAYMENT_REQUIRED. Write calls that need an author return 422 TOKEN_OWNER_INACTIVE when the person who created the key has left the organization; create a new key in that case. Error messages are Slovak when you send Accept-Language: sk or cs, otherwise English.

Scopes for CRM resources

Scopes follow the pattern <resource>:read and <resource>:write. The companies scopes cover both companies and their contact persons. users:read exposes the users lookup list only, and webhooks:manage allows creating and deleting REST hooks.

Resource	Read scope	Write scope
Companies and contacts	companies:read	companies:write
Clients	clients:read	clients:write
Leads	leads:read	leads:write
Activities	activities:read	activities:write
Tasks	tasks:read	tasks:write
Invoices	invoices:read	invoices:write
Bookings	bookings:read	bookings:write
Orders	orders:read	orders:write
Users lookup	users:read	none
REST hooks	webhooks:manage	same scope

Scopes for lookups and /me

GET /me needs no scope. Lookup lists such as /lead-origins, /lead-pipelines, /lost-reasons, /activity-types, /tags, /custom-fields, /projects, /booking-services and /booking-staff need the read scope of the related entity, as shown in the x-dakoty-scope field of each operation in the API reference. When Dakoty issues a key you can start from a preset: the automation preset (read and write for leads, companies, activities and tasks, read for clients, invoices, bookings, orders and users, plus webhooks:manage) or a read-only preset.

Legacy e-shop keys and GET /orders

Older keys were created for the e-shop and storefront integrations and carry scopes such as products:read, stock:read or catalog:read. The names orders:read and orders:write exist in both worlds, so holding them proves nothing. Dakoty treats a key as a v1 key only when it holds at least one CRM scope or webhooks:manage. A key whose scopes are only orders:read plus legacy e-shop scopes is treated as legacy.

Why GET /orders returns LEGACY_KEY_NOT_ALLOWED

GET /orders lists orders together with customer names, e-mail addresses, phone numbers and addresses. For that reason it is available only to v1 keys, even if a legacy key holds orders:read. A legacy key receives 403 with the code LEGACY_KEY_NOT_ALLOWED. The fix is to create a new key with v1 scopes, for example the automation preset or any key that includes a CRM scope. Legacy keys keep working on the e-shop endpoints they were made for, such as /products and the single-order endpoints.

{
  "error": {
    "code": "LEGACY_KEY_NOT_ALLOWED",
    "message": "This legacy API key cannot use the Developer API v1. Create a new key under Integrations.",
    "detail": null
  }
}

Key hygiene in code

Keep keys out of source control and client-side code, use one key per integration so you can revoke it alone, and grant only the scopes the integration uses. The help article Securing integrations (Slovak) lists the operational rules for key rotation and leaks.