SAPI-SK — autentifikácia (OAuth2)

SAPI-SK používa OAuth 2.0 grant client_credentials. Za client ID a secret dostanete krátkodobý access token (JWT, 15 minút) a dlhodobý refresh token (30 dní) na obnovu bez opätovného posielania secretu.

Získanie tokenov

Client ID a secret získate v paneli na /dashboard/sapi (secret sa zobrazí iba raz). Vymeníte ich za pár tokenov:

POST https://api.efaktura.sk/sapi/auth/token
Content-Type: application/json

{
  "client_id": "sapi_live_xxxxxxxxxxxx",
  "client_secret": "••••••••••••••••••••",
  "grant_type": "client_credentials",
  "scope": "document:send document:receive"
}

Odpoveď (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "document:send document:receive",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_expires_in": 2592000
}

Polia refresh_token a refresh_expires_in sú naše rozšírenie. Pôvodná SAPI schéma ich v odpovedi zabudla deklarovať, hoci endpoint /auth/renew refresh token vyžaduje — preto ich vraciame.

Použitie access tokenu

Do všetkých dokumentových volaní pošlite access token v hlavičke Authorization: Bearer <access_token> spolu s hlavičkou X-Peppol-Participant-Id.

Kontrola stavu tokenu

Pred obnovou si viete overiť, koľko tokenu zostáva. Ak should_refresh je true (menej než 3 minúty do expirácie), token proaktívne obnovte.

GET https://api.efaktura.sk/sapi/auth/token/status
Authorization: Bearer <access_token>

// 200
{
  "valid": true,
  "token_type": "access",
  "client_id": "sapi_live_xxxxxxxxxxxx",
  "issued_at": "2026-07-04T10:00:00.000Z",
  "expires_at": "2026-07-04T10:15:00.000Z",
  "expires_in_seconds": 542,
  "should_refresh": false,
  "refresh_recommended_at": "2026-07-04T10:12:00.000Z"
}

Obnova tokenov (rotácia)

Refresh token vymeníte za nový pár. Ide o rotáciu: pôvodný refresh token sa zneplatní a dostanete nový. Preto si vždy uložte novú dvojicu z odpovede.

POST https://api.efaktura.sk/sapi/auth/renew
Content-Type: application/json

{ "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

// 200 — rovnaký tvar ako /auth/token (nový access aj nový refresh)

Reuse detection. Ak sa použije už rotovaný (zneplatnený) refresh token, považujeme to za kompromitáciu a zneplatníme celú rodinu tokenov odvodených z pôvodného. V takom prípade sa musíte znovu autentifikovať cez /auth/token.

Zneplatnenie (revoke)

Pri odhlásení alebo podozrení na únik refresh token zneplatníte. Operácia je idempotentná — vždy vráti úspech (aj pri neznámom tokene, podľa RFC 7009).

POST https://api.efaktura.sk/sapi/auth/revoke
Content-Type: application/json

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type_hint": "refresh_token" }

// 200
{ "success": true, "message": "Token revoked successfully", "timestamp": "2026-07-04T10:20:00.000Z" }

Ochrana proti hádaniu (lockout)

Po 5 neúspešných pokusoch o token pre daný client_id sa klient dočasne zamkne na 15 minút — ďalšie volanie vráti 423 (SAPI-AUTH-005). Úspešná autentifikácia počítadlo vynuluje.

IP allowlist

Ku klientovi si voliteľne nastavíte zoznam povolených IP adries. Ak je vyplnený a požiadavka o token príde z inej IP, vráti sa 403 (SAPI-AUTH-004).