Autentifikácia a tokeny

OAuth 2.0 client_credentials, kontrola platnosti, obnova a zrušenie tokenov.

SAPI+ používa OAuth 2.0 client_credentials. Klient získa access_token pomocou pridelených client_id a client_secret; pri chránených volaniach posiela hlavičku:

Authorization: Bearer VAS_ACCESS_TOKEN

Klientské prístupy získate pri aktivácii SAPI+. Uchovávajte ich na serveri v bezpečnom úložisku. Tajný kľúč ani tokeny nevkladajte do klientského JavaScriptu, verejného repozitára alebo logov.

Endpoint - Získanie tokenu

Stav: Implementované, Nasadené: Sandbox

POST /v1/sapi/auth/token
Content-Type: application/json

Príklad requestu:

{
  "client_id": "client_123",
  "client_secret": "secret_value",
  "grant_type": "client_credentials",
  "scope": "document:send document:receive"
}

Request body:

Pole	Povinné	Popis
`client_id`	áno	Identifikátor klienta pridelený v Doklado.
`client_secret`	áno	Tajný kľúč klienta. Nutné bezpečne uchovávať v KMS.
`grant_type`	áno	Hodnota musí byť `client_credentials`.
`scope`	nie	Voliteľný rozsah oprávnení, napr. `document:send document:receive`.

Úspešná odpoveď: HTTP 200

{
  "access_token": "<jwt_access_token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "document:send document:receive",
  "refresh_token": "<refresh_token_if_supported>"
}

Response body:

Pole	Typ	Popis
`access_token`	string	JWT token pre API volania.
`token_type`	string	Vždy `Bearer`.
`expires_in`	integer	Životnosť access tokenu v sekundách.
`scope`	string	Priznaný scope, ak sa používa.
`refresh_token`	string	Voliteľné pole, ak implementácia podporuje obnovu tokenu cez refresh token.

Chybové stavy:

HTTP	Príčina
`400`	Neplatný request, chýbajúce pole alebo nepodporovaný `grant_type`.
`401`	Neplatné `client_id` alebo `client_secret`.
`403`	Klient nemá povolený prístup alebo jeho účet nie je aktívny.
`423`	Účet alebo klient je dočasne zablokovaný.

Endpoint - Kontrola stavu tokenu

Stav: Implementované, Nasadené: Sandbox

GET /v1/sapi/auth/token/status
Authorization: Bearer <access_token>

Úspešná odpoveď: HTTP 200

{
  "valid": true,
  "expires_in_seconds": 420,
  "should_refresh": false,
  "refresh_recommended_at": "2026-05-11T12:25:00Z",
  "expires_at": "2026-05-11T12:30:00Z"
}

Pole	Typ	Popis
`valid`	boolean	Či je token momentálne platný.
`expires_in_seconds`	integer	Zostatok platnosti v sekundách.
`should_refresh`	boolean	`true`, ak sa odporúča token obnoviť pred ďalším volaním.
`refresh_recommended_at`	datetime	Odporúčaný čas obnovenia tokenu.
`expires_at`	datetime	Presný čas expirácie tokenu v ISO 8601.

Odporúčané použitie: endpoint volajte pred odoslaním dokumentu, ak klient potrebuje overiť, že token bude platný počas prípravy requestu.

Expirácia tokenu

Platnosť určujte z expires_in, nie z pevne nastavenej konštanty. Príklad odpovede vyššie uvádza 900 sekúnd (15 minút). Token uchovajte spolu s časom expirácie.

Obnova tokenu

POST /v1/sapi/auth/renew prijíma JSON telo s poľom refresh_token. Použite hodnotu získanú pri autentifikácii. Príklad používa SAPI_BASE_URL vrátane /v1 podľa prvého volania.

curl --request POST --fail-with-body --silent --show-error \
  "$SAPI_BASE_URL/sapi/auth/renew" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "refresh_token": "VAS_REFRESH_TOKEN"
  }'

Konkrétny formát odpovede nie je v aktuálnych podkladoch definovaný. Ak odpoveď obsahuje nové tokeny a čas expirácie, aktualizujte ich v úložisku integrácie. Ak nemáte použiteľný refresh token, získajte nový access token cez client_credentials.

Zrušenie tokenu

POST /v1/sapi/auth/revoke prijíma token na zrušenie a token_type_hint. Nasledujúci príklad ruší refresh token:

curl --request POST --fail-with-body --silent --show-error \
  "$SAPI_BASE_URL/sapi/auth/revoke" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "token": "VAS_REFRESH_TOKEN",
    "token_type_hint": "refresh_token"
  }'

Pri renew ani revoke príklady neposielajú hlavičku Authorization; token je súčasťou JSON tela. Formát odpovede a presné účinky zrušenia na ostatné vydané tokeny nie sú v aktuálnych podkladoch definované.

Prístupy client_id a client_secret získate pri aktivácii SAPI+.

Was this page helpful?