Autentizace

Každý požadavek na API nese klíč aplikace. K němu se přidává token uživatele, pokud aplikace jedná jménem přihlášeného člověka. Obojí platí společně — nejsou to dvě alternativy.

Co	Hlavička	Kdo to je	Povinné
Klíč aplikace	X-API-Key: <klíč>	vaše aplikace (partnerská integrace, mobilní aplikace)	ano, u každého požadavku
Token uživatele	Authorization: Bearer <token>	přihlášený člověk	ne

Bez tokenu se volání vyhodnotí jako volání nepřihlášeného návštěvníka (role guest): aplikace vidí totéž co anonymní návštěvník webu — veřejné výpisy, články a inzeráty se zamaskovanými osobními údaji. S tokenem se volání vyhodnotí s rolemi toho uživatele, v mezích rolí povolených aplikaci.

# jako anonymní návštěvník
curl "https://vas-web.cz/api/blog/article/get-all?limit=5" \
  -H "X-API-Key: $API_KEY"

# jako přihlášený uživatel
curl "https://vas-web.cz/api/blog/article/get-all?limit=5" \
  -H "X-API-Key: $API_KEY" \
  -H "Authorization: Bearer $TOKEN"

Klíč aplikace

Klíč je hlavička X-API-Key a volá se jen přes HTTPS. Identifikuje aplikaci, ne uživatele. Má tvar coolcms_ a 64 hexadecimálních znaků.

Jak klíč získat

1. Požádejte administrátora webu o klíč pro svou aplikaci.
2. Administrátor aplikaci založí v Nastavení → Aplikace s přístupem k Api a nastaví u ní povolené role a limity. Postup pro něj popisuje Aplikace s přístupem k Api.
3. Klíč vám předá. Uložte si ho na místo, odkud ho bude číst vaše aplikace.

Celý klíč se zobrazí jen jednou

Administrátor ho vidí v plném znění jen při založení aplikace nebo vydání nového klíče. Systém ukládá pouze otisk, takže ztracený klíč nejde zobrazit znovu — jen vydat nový. V administraci se pro rozlišení klíčů ukazuje pouze prvních 16 znaků.

Vypnutí, další klíč, expirace a zrušení

Aplikace může mít víc klíčů (nejvýš 5 platných) a každý klíč může mít expiraci — datum a čas, kdy přestane platit. Administrátor může aplikaci vypnout a znovu zapnout, vydat jí další klíč, klíči nastavit nebo zrušit expiraci, klíč zrušit nebo celou aplikaci trvale zrušit. Změna platí hned:

Co administrátor udělá	Co dostane vaše aplikace
vypne aplikaci	401 s kódem 501 u každého požadavku (s kterýmkoli klíčem), dokud ji znovu nezapne
vydá další klíč	dosavadní klíče platí dál; nový klíč nasadíte, až se vám to hodí
nastaví klíči expiraci	klíč platí do zadaného okamžiku, pak vrací 401 s kódem 501
zruší klíč	tento klíč vrací 401 s kódem 501 hned; ostatní klíče aplikace platí dál
zruší aplikaci	401 s kódem 501 natrvalo u všech jejích klíčů; zrušenou aplikaci nejde zapnout ani jí vydat klíč

Vypršelý klíč dostane stejnou odpověď jako neznámý klíč. Dostane-li aplikace, která dosud fungovala, najednou 401 s kódem 501, ozvěte se administrátorovi webu. Limity požadavků patří celé aplikaci, ne jednotlivému klíči — všechny klíče aplikace je sdílejí.

Výměna klíče

Klíč jde vyměnit bez výpadku: administrátor starému klíči nastaví expiraci, vydá vám nový klíč a vy ho nasadíte; do expirace platí oba. Počítejte s tím už při stavbě aplikace:

• Klíč čtěte z konfigurace, ne natvrdo z kódu — na serveru z proměnné prostředí nebo konfiguračního souboru, aby výměna klíče nevyžadovala nové nasazení kódu.
• Mobilní aplikace má klíč obvykle v sestavení a výměna znamená novou verzi. Domluvte se s administrátorem na expiraci starého klíče s dostatečnou rezervou na schválení nové verze v obchodě s aplikacemi a na to, kdy uživatelé starou verzi přestanou používat.

Zacházení s klíčem

• Server–server: klíč držte v tajnosti na svém serveru, mimo repozitář a mimo logy. Neposílejte ho do prohlížeče ani do aplikace v telefonu.
• Mobilní aplikace a skript v prohlížeči: klíč, který je součástí aplikace, není tajný — každý ho z ní vytáhne. Sám o sobě proto dává jen přístup na úrovni nepřihlášeného návštěvníka. Skutečnou hranicí zůstávají práva přihlášeného uživatele.
• Uniklý klíč dává cizímu jen to, co vidí nepřihlášený návštěvník webu, a čerpá limity vaší aplikace. Požádejte administrátora o nový klíč a o zrušení uniklého — zrušený klíč přestane platit hned.

Klíč nerozšiřuje práva uživatele, jen je může omezit

Přes aplikaci se uplatní jen role, které jí administrátor povolil. Administrátor webu, který se přihlásí přes partnerskou aplikaci bez role admin, má v ní jen práva běžného uživatele. Viz Povolené role aplikace.

Když klíč chybí nebo neplatí

Chybějící, špatný, vypnutý, zrušený i vypršelý klíč vrací vždy stejnou odpověď — HTTP 401:

{"success":false,"message":"A valid application key (X-API-Key) is required.","data":null,"code":501}

Odpověď záměrně neříká, o který z případů jde. Kód 501 je API_UNAUTHORIZED. Nezaměňujte ho s 103 (neplatný nebo vypršelý token uživatele) a s 400 (zamítnuté oprávnění, HTTP 403).

Endpointy bez klíče

Čtyři adresy volají třetí strany, které klíč poslat nemohou. Klíč nevyžadují:

Adresa	Kdo ji volá
/api/system/payment/execute	platební brána (oznámení i návrat zákazníka)
/api/system/payment/delivery	brána nebo SMS agregátor — oznámení o doručení
/api/system/payment/express-execute	agregátor expresních SMS plateb
/api/system/auth/oauth-deauthorize-callback	poskytovatel přihlášení — zrušení oprávnění

Partnerské aplikace je nevolají. Všechno ostatní, včetně přihlášení, obnovy tokenu a odhlášení, klíč vyžaduje.

Web a administrace klíč nepotřebují

Volají API vnitřní cestou, bez HTTP. Klíč se týká jen externích aplikací.

JWT — uživatelská identita

Přihlášení, obnova i odhlášení jsou běžná volání API, takže také nesou klíč aplikace.

Endpoint	Co dělá
POST /api/system/auth/login	přihlásí, vrátí pár tokenů
POST /api/system/auth/refresh	obnoví pár
POST /api/system/auth/logout	odhlásí
GET /api/system/auth/me	profil přihlášeného
GET/POST /api/system/auth/is-auth-valid	ověří token z hlavičky Authorization nebo z těla (token)

Přihlašuje se přezdívkou nebo e-mailem

Pole se jmenuje username, ale přijme obojí. Údaj ve tvaru e-mailu se hledá nejdřív mezi e-maily, teprve pak mezi přezdívkami.

Přihlášení přes cizí službu nemá HTTP obal

Google, Facebook a další poskytovatelé se ověřují na webu, který identitu prověří přímo u poskytovatele. Endpoint, který by přijal hotový výsledek zvenčí, neexistuje — holé „poskytovatel a identifikátor“ by stačilo k převzetí cizího účtu.

Tělo požadavku

Formulářové kódování, ne JSON

Přihlašovací endpointy (login, refresh, logout) čtou jen formulářové tělo. JSON tělo se nepřečte.

Hlavička

X-API-Key: <klíč aplikace>
Authorization: Bearer <access token>

Neplatný token se nenahrazuje hostem

Chybí-li Authorization, jedná se o návštěvníka. Je-li ale token neplatný, vypršelý nebo zneplatněný, vrátí API 401 s kódem 103, ne tiše hostovský přístup. Aplikace musí token obnovit nebo se znovu přihlásit. Výjimkou jsou veřejné akce, které token v hlavičce nečtou (přihlášení, obnova tokenu, zapomenuté heslo) — ty se vyhodnocují vždy jako návštěvník.

Platnost

Token	Platnost
Přístupový	15 minut
Obnovovací	60 dní, rotuje se

Rotace a detekce krádeže

Každá obnova vrátí nový pár. Starý obnovovací token přestane platit.

Použití starého obnovovacího tokenu zneplatní celou větev

Systém to vyhodnotí jako krádež a odhlásí i vás. Odpověď má kód 103. Ukládejte vždy poslední vrácený pár.

Kdy token přestane platit dřív

Odhlášení zapíše přístupový token na seznam zakázaných. Zablokování nebo deaktivace účtu, změna nebo obnova hesla (i administrátorem) a žádost o zrušení účtu navíc zneplatní všechny dosud vydané tokeny účtu — přístupové i obnovovací.

Váš klient musí zpracovat 401 kdykoli

Ne až po patnácti minutách. Odhlášení z jiného zařízení, změna hesla nebo zablokování účtu token zneplatní hned.

Odmítnuté přihlášení

Situace	Odpověď
neznámý účet nebo špatné heslo	kód 110 — obojí stejně, aby nešlo zjistit, který účet existuje
neaktivní účet	kód 109, až po správném hesle
zablokovaný účet	kód 104, až po správném hesle
účet čeká na zrušení	kód 117; data.scheduledAt nese datum zrušení (další položky data slouží webu)
zrušený účet	kód 110 — původní přezdívka ani e-mail už k účtu nevedou
příliš mnoho neúspěchů	HTTP 429, viz Limity

Obnova tokenu u neaktivního, zablokovaného nebo rušeného účtu vrátí kód 102.

Zrušení účtu se z API nespouští

Žádost, potvrzení i storno zrušení účtu probíhají na webu. Rušený účet se během ochranné lhůty nepřihlásí; zrušený (anonymizovaný) účet nejde uložit — user/save vrátí 120.

Změna a obnova hesla

Hesla a klíče jen v těle POST, nikdy v adrese

Adresa se zapisuje do logů serveru i proxy a zůstává v historii. Akce níž čtou hesla, klíče a tokeny výhradně z těla (formulářového i JSON); stejný údaj v adrese se ignoruje a akce skončí, jako by chyběl.

Změna hesla přihlášeného uživatele

POST /api/system/user/update-password s hlavičkou Authorization:

Pole těla	Význam
currentPassword	současné heslo — povinné
password	nové heslo, aspoň 8 znaků

Výsledek	Kód
změněno	0; data nese nový pár token, refreshToken a payload
chybějící nebo špatné současné heslo	108
krátké nové heslo	611
příliš mnoho špatných pokusů	404

Po změně hesla si uložte nový pár tokenů

Změna odvolá všechny dosavadní obnovovací tokeny účtu, i ten váš. Kdo nový pár neuloží, vypadne s vypršením přístupového tokenu. Ostatní zařízení se musí přihlásit znovu.

Zapomenuté heslo

1. /api/system/user/send-new-password?username=… pošle na e-mail účtu odkaz pro nastavení nového hesla, platný hodinu. Heslo samo se nemění a odpověď je vždy stejná, ať účet existuje, nebo ne.
2. Odkaz vede na stránku webu. Nastavení hesla dělá POST /api/system/user/reset-password s poli těla email, key a password. Neplatný, použitý nebo prošlý klíč i neznámý e-mail vracejí jeden kód 112; krátké heslo 611. Po úspěchu se odvolají všechny tokeny účtu.

Ověření tokenu

is-auth-valid bere token z hlavičky Authorization: Bearer, jinak z pole těla token. Token v adrese se nepřečte a odpověď je 103.

Neúspěšné pokusy

Zapisují se do auditního logu a do tabulky. Přihlašovací endpoint má limit 5 neúspěšných pokusů za 5 minut na dvojici účet a adresa a 20 neúspěšných pokusů za hodinu na účet ze všech adres.

Nastavení cookies