OAuth prístupové tokeny
Okrem API kľúčov berie Developer API aj OAuth prístupové tokeny. Sú pre aplikácie, ktoré si človek pripojí k svojmu účtu v Dakoty, napríklad aplikáciu Dakoty pre Zapier. Človek pripojenie raz schváli, vyberie organizáciu a aplikácia potom volá API ako on. Tvoje vlastné skripty a integrácie Make a n8n ďalej používajú API kľúče a na existujúcich kľúčoch sa nič nemení. Anglická verzia: OAuth access tokens.
Čo je OAuth pripojenie
Section titled “Čo je OAuth pripojenie”O pripojenie môžu žiadať len aplikácie, ktoré zaregistroval Dakoty. Otvorená registrácia klientov pre REST API neexistuje. Každá aplikácia má identifikátor klienta začínajúci dkapp_, tajomstvo klienta uložené na jej serveri a pevný zoznam oprávnení, o ktoré môže žiadať. Autorizácia je štandardný tok s autorizačným kódom a PKCE (S256), pričom klient sa na token endpointe overuje cez client_secret_post alebo client_secret_basic. Metadáta pre klientov sú na /.well-known/oauth-authorization-server a chránený zdroj na /.well-known/oauth-protected-resource/api/v1/public.
Prístupový token začína dk_oat_ a platí jednu hodinu. Obnovovací token začína dk_ort_ a pri každom použití sa vymení za nový. Ak sa pripojenie 180 dní nepoužije, Dakoty ho ukončí. Človek ho môže odpojiť kedykoľvek, a keď ho odoberieš z organizácie alebo deaktivuješ jeho účet, skončí okamžite.
Volanie API s tokenom
Section titled “Volanie API s tokenom”Prístupový token pošli tak ako API kľúč:
curl -sS https://api.dakoty.com/api/v1/public/me \ -H "Authorization: Bearer $DAKOTY_ACCESS_TOKEN"Neznámy, expirovaný alebo zrušený token vráti 401 UNAUTHORIZED s hlavičkou WWW-Authenticate, ktorá ukazuje na metadáta chráneného zdroja:
WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://api.dakoty.com/.well-known/oauth-protected-resource/api/v1/public"401 je signál na obnovenie tokenu. Dočasná chyba na našej strane vráti 503, nikdy 401, takže klient kvôli nej pripojenie nezahodí.
Prístup = udelené oprávnenia ∩ rola človeka
Section titled “Prístup = udelené oprávnenia ∩ rola človeka”Oprávnenia (scopes) pripojenia sú to, s čím človek súhlasil. Nikdy nedávajú viac, než dovoľuje jeho rola. Pri každej požiadavke Dakoty kontroluje obe veci: token musí mať oprávnenie, ktoré koncový bod vyžaduje, a zároveň ho musí podporovať aktuálna rola pripojeného človeka v danej organizácii. Rola sa číta pri požiadavke, takže zmena platí pri ďalšom volaní: povýš človeka a volanie prejde, odober oprávnenie a volanie sa odmietne, a to s tým istým tokenom.
| Scope | Čo potrebuje rola človeka |
|---|---|
companies:read, clients:read, leads:read, activities:read, tasks:read | oprávnenie zobraziť danú entitu (napríklad leads.view) |
tasks:read pri GET /projects | navyše projects.view (rola iba s tasks.view tu dostane 403 ROLE_PERMISSION_MISSING) |
companies:write, clients:write, leads:write, activities:write, tasks:write | oprávnenie upraviť aj vytvoriť entitu (napríklad leads.edit a leads.create) |
invoices:read / invoices:write | budget.view / budget.edit a budget.create |
bookings:read / bookings:write | booking.view / booking.create a booking.edit |
orders:read / orders:write | orders.view / orders.edit |
users:read | users.view |
webhooks:manage | nič, stačí scope |
Každé oprávnenie musí platiť pre všetky záznamy. API nevie zoznam zúžiť na človekove vlastné záznamy, takže rola, ktorá vidí len pridelené leady, sa odmietne, namiesto toho aby videla leady kolegov. Vlastník organizácie rolou prejde, ale stále len cez oprávnenia, ktoré pripojenie má. Scope, ktorý v tabuľke nie je, sa s OAuth tokenom nikdy použiť nedá.
Dve chyby povedia klientovi, prečo sa volanie odmietlo. Obe sú 403 a správa je po slovensky, keď pošleš Accept-Language: sk alebo cs:
{ "error": { "code": "ROLE_PERMISSION_MISSING", "message": "Tvoja rola v Dakoty toto nedovoľuje (chýba oprávnenie Leady – zobraziť).", "detail": null }}{ "error": { "code": "ROLE_SCOPE_LIMITED", "message": "Tvoja rola v Dakoty vidí iba tvoje záznamy; toto prepojenie potrebuje prístup ku všetkým záznamom.", "detail": null }}ROLE_PERMISSION_MISSING znamená, že rola nemá potrebné oprávnenie a administrátor ho môže pridať. ROLE_SCOPE_LIMITED znamená, že oprávnenie rola má, ale len pre pridelené záznamy. Volanie, ktorého scope pripojenie nemá, vráti ďalej 403 FORBIDDEN, rovnako ako pri API kľúčoch. Opätovné pripojenie nepomôže pri žiadnej z rolových chýb: rolu musí zmeniť človek (alebo administrátor).
Rovnaké pravidlo platí pre REST hooky: prihlásenie na udalosť, ktorú rola nemôže čítať, skončí 403 a doručovanie sa zastaví, kým rola oprávnenie nemá; pozri REST hooky. Samotné pripojenie nie je API kľúč: nezobrazuje sa v zozname API kľúčov a nezapočítava sa do limitu kľúčov organizácie.
Súhlas a Pripojené aplikácie
Section titled “Súhlas a Pripojené aplikácie”Obrazovka súhlasu porovná každé požadované oprávnenie s rolou človeka vo zvolenej organizácii (rovnakou kontrolou, aká beží pri každom volaní). Oprávnenie, ktoré rola nepokrýva, sa z pripojenia neodoberá. Je udelené, ale volania, ktoré ho potrebujú, vrátia 403, kým administrátor roli oprávnenie nepridá. Kontrola sa zopakuje, keď človek zvolí inú organizáciu. Oprávnenie môže vyžadovať viac práv (pozri tabuľku vyššie), takže oprávnenie zobrazené ako povolené môže byť pri jednom endpointe stále odmietnuté.
Pripravujeme: sivé zobrazenie takýchto oprávnení s dôvodom a opätovnú kontrolu pri zmene organizácie na obrazovke súhlasu prinesie ďalšie vydanie webu Dakoty.
Schválené pripojenia sú v časti Pripojené aplikácie v profile človeka; administrátori s oprávnením na integrácie tam vidia aj pripojenia celej organizácie. Pripojenie Zapieru ukazuje udelené oprávnenia a počet REST hookov (Zapy, ktoré počúvajú udalosti z Dakoty). Odpojenie zruší pripojenie spolu s prístupovými a obnovovacími tokenmi a zmaže všetky jeho REST hooky, takže Zapy prestanú dostávať udalosti okamžite. Rovnako pôsobí odobratie človeka z organizácie. Schválenie sa zapíše do auditu s oprávneniami a druhom pripojenia, odpojenie s druhom pripojenia a počtom zmazaných hookov.
Odpojenie sa robí v aplikácii Dakoty, nie je súčasťou vývojárskeho API.
GET /me pri OAuth pripojení
Section titled “GET /me pri OAuth pripojení”GET /me nepotrebuje scope. Pri OAuth tokene uvádza aj človeka, ktorý aplikáciu pripojil, a token.id je identifikátor záznamu pripojenia, ktorému patria REST hooky aplikácie:
{ "data": { "organization": { "id": "…", "name": "Acme s.r.o.", "slug": "acme" }, "token": { "id": "…", "name": "Zapier – Jana Nováková", "scopes": ["leads:read", "leads:write", "webhooks:manage"], "expires_at": null }, "auth": "oauth", "user": { "id": "…", "name": "Jana Nováková", "email": "jana@example.com" }, "api_version": "2026-10-01", "limits": { "requests_per_minute": 120, "org_requests_per_minute": 600 } }}Pri API kľúči je v odpovedi "auth": "api_key" a pole user chýba. Limity požiadaviek sa počítajú na pripojenie a na organizáciu, rovnako ako pri kľúčoch. Organizácia s ukončeným predplatným dostane pri oboch druhoch prístupu 402 PAYMENT_REQUIRED.