API tokeny a OAuth klienti v praxi

Tato kapitola popisuje, jak integrace prakticky získá a používá přístup do TAS: statický API token, OAuth klienta typu klient-server i OAuth klienta, ke kterému přístup schvaluje uživatel. Správu tokenů a klientů v administraci (vytvoření, zneplatnění, rotace) popisuje článek Přístup k API – tady navazujeme z pohledu integrátora, který už token nebo klienta má a chce ho použít.

API token

Nejjednodušší cesta pro integraci mezi servery. Token vám vygeneruje administrátor s rolí $ApiTokenAdmin na obrazovce Přístup k API a předá vám ho (zobrazí se jen jednou). Používáte ho v každém volání:

curl "https://vase-tas.cz/tasks" -H "Authorization: Bearer <api-token>"

Token zastupuje jeden systémový uživatel a má přesně jeho práva – žádné rozsahy (scopes) u API tokenu neexistují. Platí nejdéle 730 dní od vygenerování (výchozí platnost 365 dní), poté přestane fungovat a je potřeba vygenerovat nový.

Jeden token, jeden účel
Pro každou integraci nechte administrátora vytvořit samostatný systémový uživatel s jen těmi právy, která integrace potřebuje, a samostatný token. Zneplatnění jedné integrace pak neovlivní ostatní.

OAuth klient typu Důvěrný (server-server integrace)

Důvěrný klient se hodí tam, kde o přístup nežádá konkrétní uživatel – integrace se autentizuje přímo jako vybraný systémový uživatel pomocí Client ID a Client secretu (grant client_credentials):

curl -X POST "https://vase-tas.cz/oauth/token" \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 28800
}

Přístupový token se posílá stejně jako API token, v hlavičce Authorization: Bearer <access_token>. Platí typicky 8 hodin (expires_in v sekundách) – po vypršení integrace zavolá /oauth/token znovu. U client_credentials TAS refresh token nevydává.

Client ID a Client secret vám vytvoří a předá administrátor na obrazovce Přístup k API › OAuth klienti. Client secret se podobně jako token zobrazí jen jednou.

OAuth klient typu Veřejný (aplikace, které uživatel sám schvaluje přístup)

Veřejný klient nemá Client secret – místo toho používá autorizační kód s PKCE a o přístup žádá vždy konkrétní uživatel. Tímto způsobem se k TAS připojují například AI asistenti (viz článek MCP server).

  1. Aplikace vygeneruje code_verifier (náhodný řetězec) a z něj code_challenge (SHA-256, base64url).
  2. Aplikace přesměruje uživatele na: `` GET /oauth/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&code_challenge=<challenge>&code_challenge_method=S256&state=<state> ``
  3. TAS přesměruje přihlášeného uživatele na obrazovku souhlasu (/oauth/consent/...), kde vidí jméno aplikace a adresu, na kterou bude po schválení přesměrován, a přístup potvrdí nebo odmítne.
  4. Po schválení TAS přesměruje zpět na redirect_uri s parametrem code.
  5. Aplikace kód vymění za token: ``bash curl -X POST "https://vase-tas.cz/oauth/token" \ -d "grant_type=authorization_code" \ -d "code=<code>" \ -d "redirect_uri=<redirect_uri>" \ -d "code_verifier=<verifier>" \ -d "client_id=<client_id>" ` Odpověď obsahuje access_token, expires_in a tentokrát i refresh_token pro obnovení bez opakovaného souhlasu uživatele (grant_type=refresh_token`).

Token zastupuje práva uživatele, který souhlas udělil – ne systémového uživatele. Přehled, komu aplikace přístup udělili a kdy byl naposledy použit, je v Přístup k API › OAuth oprávnění; uživatel i administrátor s rolí $ApiTokenAdmin tam mohou přístup kdykoli odebrat.

Rozsahy (scopes) nejsou podporované
TAS 5.19.12 nerozlišuje rozsahy OAuth přístupu. Token nebo klient má vždy celá práva uživatele, kterého zastupuje – navrhujte integraci podle toho, kterého uživatele (nebo systémového uživatele) k ní připojíte, ne podle předpokládaného rozsahu oprávnění.

Rotace a zneplatnění

Co rotujeteJak
API tokenVygenerujte nový na Přístup k API, starý zneplatněte akcí Zneplatnit. Zneplatnění je okamžité a nevratné.
Client secret důvěrného klientaAdministrátor použije u klienta akci Vygenerovat nový Client secret – starý přestane fungovat okamžitě, novou hodnotu zadejte do integrace ihned.
Přístup veřejného klientaUživatel nebo administrátor odebere oprávnění v Přístup k API › OAuth oprávnění; aplikace musí o souhlas požádat znovu.

Podrobný popis obrazovek a rolí najdete v článku Přístup k API, bezpečné uložení Client secretu nebo API klíče na straně vaší integrace (pokud leží v TAS, např. ve skriptu výpočtu) popisuje článek Trezor.

Omezení počtu požadavků na přihlašovací endpointy
Endpointy /oauth/authorize, /oauth/token, /oauth/revoke a registrace klienta přijímají nejvýše 60 požadavků za minutu z jedné IP adresy. Při překročení TAS odpoví chybou „too many requests“ – integraci, která si tokeny obnovuje příliš často, upravte tak, aby token používala až do konce jeho platnosti.

Související: Přístup k API, REST API: přihlášení a základní volání, MCP server, Trezor.

REST API: přihlášení a základní volání

Přístup k API
Team assistant (opens in a new tab)

Powered by HelpDocs (opens in a new tab)