Autentizace

Každý požadavek na Sursa API nese v hlavičce Authorization klíč API nebo přístupový token OAuth některé aplikace:

Authorization: Bearer kb_3f9c…

Klíč identifikuje organizaci a rozhoduje o tom, co požadavek smí vidět a měnit: určuje to jeho role, rozsahy, datový profil a kolekce. Na adrese API nejsou relace ani cookies. Každý požadavek se autentizuje samostatně, proto lze se stejným klíčem posílat požadavky paralelně i z více serverů.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Starší integrace mohou klíč posílat místo toho v hlavičce X-API-Key. Ta se stále přijímá, nový kód by ale měl používat Authorization: Bearer.

Druhy přihlašovacích údajů

Údaj	Podoba	Kde funguje
Klíč API organizace	`kb_…`	Všechny operace API v rámci role, rozsahů, datového profilu a kolekcí klíče.
Klíč vlastního zdroje	`kbsrc_…`	Jen operace push vlastního zdroje, ke kterému patří (`/v1/push/sources/{source_id}/…`).
Přístupový token OAuth	`kbat_…`	Operace reference API v rámci rozsahů tokenu. Token z `POST /oauth/token` získaný autorizačním kódem jedná jménem zaměstnance, který udělil souhlas; token `client_credentials` jedná za organizaci stejně jako klíč API. Platí 1 hodinu.

Všechny se odesílají stejně. Klíč vlastního zdroje nemůže mimo svůj zdroj nic číst, vyhledávat ani měnit; používejte ho tam, kde klíč uchovává třetí strana, například integrační platforma.

Chyby autentizace

Stavový a chybový kód	Co znamená	Co dělat
`401` `auth.not_authenticated`	Klíč chybí, je chybně zadaný nebo odvolaný.	Zkontrolujte hlavičku a hodnotu klíče.
`401` `api_keys.expired`	Klíči vypršela platnost.	Vytvořte nový klíč a nahraďte jím starý.
`401` `sources.push_key_invalid`	Klíč vlastního zdroje je chybný, odvolaný nebo patří jinému zdroji.	Zkontrolujte klíč a ID zdroje v cestě.
`401` `oauth.token_expired`	Přístupovému tokenu OAuth vypršela platnost.	Získejte nový pomocí obnovovacího tokenu.
`403` `api_keys.scope`	Klíč nemá rozsah pro tuto operaci.	Přidejte rozsah, nebo použijte klíč, který ho má.
`403` `api_keys.feature_disabled`	Tarif organizace nezahrnuje klíče API.	Obraťte se na administrátora organizace.
`403` `api_keys.ip_not_allowed`	Požadavek přichází z adresy, která není mezi povolenými adresami klíče.	Volejte z povolené sítě, nebo změňte adresy klíče.
`403` `api_keys.mcp_only`	Osobní klíč MCP byl použit mimo operaci `/mcp`.	Pro API použijte klíč API organizace.
`403` `oauth.operation_not_allowed`	Operace není součástí veřejného API, proto ji token OAuth nemůže volat.	Použijte operaci z reference API.
`403` `org.suspended`	Organizace je pozastavená. Její data zůstávají zachována.	Obraťte se na administrátora organizace.

403 znamená, že požadavek prošel autentizací, ale není povolený. Na objekt, který klíč vidět nesmí, přijde odpověď 404 stejně jako na objekt, který neexistuje, takže klíč nemůže zjistit, co leží mimo jeho přístup.

Požadavky z pohledu datového profilu

Klíč s rolí admin může zkontrolovat, co by viděla jiná skupina lidí: hlavička X-View-As provede požadavek s datovým profilem a případně i s rolí, které v ní uvedete.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

Požadavky v tomto režimu jen čtou: jakákoli změna vrátí 403 s kódem view_as.read_only. Token OAuth ani klíč bez role admin hlavičku X-View-As použít nemohou: odpovědí je 403 s kódem view_as.admin_key_required. Na hlavičku, která neuvádí žádný existující profil, přijde odpověď 400 s kódem view_as.invalid_header.

Aplikace v prohlížeči

API přijímá požadavky z jakéhokoli webového původu (Access-Control-Allow-Origin: *) a nikdy nepoužívá cookies, takže ho stránka může volat přes fetch. Klíč je pak součástí stránky a vidí ho každý, kdo ji používá. Z prohlížeče volejte API jen s klíčem, který lze těmto uživatelům bez obav ukázat, například s klíčem viewer omezeným na veřejné kolekce, nebo mezi prohlížeč a Sursu vložte vlastní server.

Co může jen zaměstnanec

Klíč API organizace jedná za organizaci, ne za člověka. Dvě části API patří lidem, proto fungují jen s tokenem, který jedná jménem zaměstnance: s relací v Surse nebo s přístupovým tokenem OAuth vydaným se souhlasem zaměstnance.

Konverzace patří člověku. Klíč API organizace vidí v GET /v1/conversations jen konverzace, které sám zahájil. Veřejné API nemá operaci, která by konverzaci zahájila, takže pro klíč je seznam obvykle prázdný a konverzace zaměstnanců se mu nikdy nezobrazí. Otázky bez konverzace přes POST /v1/ask nebo POST /v1/chat fungují s jakýmkoli klíčem, který má rozsah ask. Chcete-li vypsat konverzace zaměstnance a přečíst historii jedné z nich pomocí GET /v1/conversations/{conv_id}, volejte API s tokenem OAuth jménem tohoto zaměstnance. Token vidí jen vlastní konverzace tohoto zaměstnance; na jakoukoli jinou konverzaci přijde odpověď 404 s kódem conversations.not_found.

Kartu ověřuje jen zaměstnanec. Ověření potvrzuje, že obsah zkontroloval člověk, proto POST /v1/cards/{card_id}/verification/verify a POST /v1/cards/{card_id}/verify vyžadují relaci nebo token OAuth jménem zaměstnance, který smí kartu ověřit. S klíčem API organizace nebo s tokenem client_credentials vracejí 400 s kódem cards.verify_user_account_required. Obvyklé kontroly mají přednost: na kartu, kterou klíč nevidí, přijde odpověď 404, a klíč, který ji ověřit nesmí, dostane 403.