Overenie a oprávnenia (scopes)

Každá požiadavka na Developer API sa overuje API kľúčom organizácie, ktorý sa posiela ako Bearer token. Kľúč má pevný zoznam oprávnení (scopes) a koncový bod odpovie len vtedy, keď kľúč drží oprávnenie, ktoré ten bod vyžaduje. Anglická verzia: Authentication and scopes.

Kľúč v hlavičke Authorization

Pošlite Authorization: Bearer dk_live_... pri každej požiadavke. Kľúč určuje organizáciu, takže v adrese nie je identifikátor organizácie a nepoužíva sa prihlásenie. Kľúč môže mať dátum platnosti a dá sa kedykoľvek zrušiť. Dakoty si pamätá iba odtlačok kľúča, preto sa stratený kľúč nedá zobraziť znova a treba ho nahradiť novým.

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

Chyby overenia a prístupu

Chýbajúci, nesprávny, vypršaný alebo zrušený kľúč vráti 401 UNAUTHORIZED. Kľúč bez oprávnenia pre daný koncový bod vráti 403 FORBIDDEN a správa pomenuje chýbajúce oprávnenie. Nezaplatené predplatné organizácie vráti 402 PAYMENT_REQUIRED. Zápis, ktorý potrebuje autora, vráti 422 TOKEN_OWNER_INACTIVE, ak človek, ktorý kľúč vytvoril, už nie je v organizácii. Vtedy založte nový kľúč. Chybové správy sú po slovensky, keď pošlete Accept-Language: sk alebo cs, inak po anglicky.

Oprávnenia pre údaje v CRM

Oprávnenia majú tvar <zdroj>:read a <zdroj>:write. Oprávnenia companies pokrývajú firmy aj ich kontaktné osoby. users:read odhaľuje iba číselník používateľov a webhooks:manage dovoľuje vytvárať a mazať REST hooky.

Zdroj	Čítanie	Zápis
Firmy a kontakty	companies:read	companies:write
Klienti	clients:read	clients:write
Leady	leads:read	leads:write
Aktivity	activities:read	activities:write
Úlohy	tasks:read	tasks:write
Faktúry	invoices:read	invoices:write
Rezervácie	bookings:read	bookings:write
Objednávky	orders:read	orders:write
Číselník používateľov	users:read	žiadne
REST hooky	webhooks:manage	rovnaké oprávnenie

Oprávnenia pre číselníky a /me

Volanie GET /me nevyžaduje oprávnenie. Číselníky ako /lead-origins, /lead-pipelines, /lost-reasons, /activity-types, /tags, /custom-fields, /projects, /booking-services a /booking-staff vyžadujú čítacie oprávnenie príslušnej entity, ako ukazuje pole x-dakoty-scope pri každej operácii v referencii API. Pri vytváraní kľúča v aplikácii môžete zvoliť predvoľbu: bežné použitie pre Make, Zapier a n8n alebo len čítanie.

Staršie e-shopové kľúče a GET /orders

Staršie kľúče vznikli pre e-shop a storefront a majú oprávnenia ako products:read, stock:read alebo catalog:read. Názvy orders:read a orders:write existujú v oboch svetoch, takže samy nič nedokazujú. Dakoty berie kľúč za kľúč v1 iba vtedy, keď má aspoň jedno oprávnenie pre CRM alebo webhooks:manage. Kľúč, ktorý má len orders:read a e-shopové oprávnenia, sa považuje za starší.

Chyba LEGACY_KEY_NOT_ALLOWED pri objednávkach

GET /orders vracia zoznam objednávok aj s menami, e-mailmi, telefónmi a adresami zákazníkov. Preto je dostupný len kľúčom v1, aj keď starší kľúč drží orders:read. Starší kľúč dostane 403 s kódom LEGACY_KEY_NOT_ALLOWED. Riešením je nový kľúč s oprávneniami v1, napríklad s predvoľbou pre Make, Zapier a n8n. Starší kľúč ďalej funguje na e-shopových koncových bodoch, pre ktoré vznikol, napríklad /products a koncové body jednej objednávky.

{
  "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
  }
}

Ako s kľúčmi zaobchádzať v kóde

Nedávajte kľúče do verziovacieho systému ani do kódu vo webovom prehliadači, pre každú integráciu použite vlastný kľúč, aby ste ho mohli zrušiť samostatne, a dajte mu len oprávnenia, ktoré integrácia naozaj používa. Prevádzkové zásady pre výmenu a únik kľúčov nájdete v článku Ako zabezpečiť integrácie.