OAuth 2.0

OAuth 2.0 je vhodný pro aplikace, které chtějí přístup k účtům jiných uživatelů invo.space. Uživatel aplikaci sám povolí a vybere, ke kterému účtu (firmě) smí. Přístup může kdykoli odebrat.

Pro vlastní skripty ve svém účtu stačí API token.

Vytvoření OAuth aplikaceKopírovat odkaz

1. Otevřete Nastavení > API a webhooky.
2. V části OAuth aplikace klikněte na Nová aplikace.
3. Vyplňte:
   • Název: uživatelé ho uvidí při povolování přístupu.
   • Adresy pro přesměrování: sem pošleme uživatele po povolení nebo zamítnutí přístupu. Povolené jsou jen adresy https, nebo http na localhost a 127.0.0.1.
   • Oprávnění: oblasti, o které aplikace smí žádat, každá zvlášť pro čtení a zápis. O víc aplikace žádat nemůže.
   • Přístup server-server: viz níže.
4. Klikněte na Uložit.
5. Zobrazí se Client ID a Client secret. Client secret se zobrazí jen jednou. Zkopírujte ho na bezpečné místo a potvrďte Uložil jsem si údaje.

Aplikaci můžete později upravit nebo smazat. Smazaná aplikace a všechny její tokeny přestanou fungovat okamžitě.

OprávněníKopírovat odkaz

Každá oblast má oprávnění pro čtení (:read) a zápis (:write). Čtení stačí pro požadavky GET, ostatní metody potřebují zápis.

Například invoices:read dovolí faktury číst, ale ne vytvářet. Nastavení účtu, uživatele, API tokeny a OAuth aplikace nejsou přes OAuth dostupné vůbec.

Když token oprávnění nemá, API vrátí 403 s kódem 40301. Role uživatele v účtu platí i pro OAuth: token nesmí víc než uživatel, který přístup povolil.

Povolení přístupu uživatelemKopírovat odkaz

Adresy všech koncových bodů najdete v metadatech serveru: https://invo.space/.well-known/oauth-authorization-server.

1. Pošlete uživatele na adresu authorization_endpoint z metadat s parametry response_type=code, client_id, redirect_uri, scope (oprávnění oddělená mezerou) a state. Doporučujeme i PKCE (code_challenge a code_challenge_method=S256).
2. Uživatel se přihlásí, uvidí název aplikace a požadovaná oprávnění a vybere účet, pokud jich má víc.
3. Po kliknutí na Povolit ho pošleme na redirect_uri s parametry code a state. Po kliknutí na Zamítnout s parametrem error=access_denied.
4. Kód vyměňte za token na POST https://invo.space/api/v2/oauth/token (grant_type=authorization_code, tělo application/x-www-form-urlencoded).

curl https://invo.space/api/v2/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=KOD \
  -d redirect_uri=https://example.com/oauth/callback \
  -d code_verifier=VERIFIER

Access token posílejte v hlavičce Authorization: Bearer, stejně jako API token. Platí 1 hodinu. Nový získáte přes grant_type=refresh_token. Refresh token platí 30 dní a při každém použití se vymění za nový. Kód z přesměrování platí 10 minut.

Přístup server-serverKopírovat odkaz

Když zapnete Přístup server-server, aplikace získá token bez přihlášení uživatele, přes grant_type=client_credentials:

curl https://invo.space/api/v2/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d "scope=invoices:read"

Token pak jedná za uživatele, který aplikaci vytvořil, v účtu, ve kterém ji vytvořil, a jen s oprávněními aplikace. Adresy pro přesměrování nejsou potřeba, když aplikace přihlášení uživatelů nepoužívá.

AI asistenti a MCP klientiKopírovat odkaz

Klienti jako Claude nebo ChatGPT se zaregistrují sami přes POST https://invo.space/api/v2/oauth/register (RFC 7591). OAuth aplikaci pro ně vytvářet nemusíte. Uživatel jim jen povolí přístup stejně jako jiné aplikaci.

Odebrání přístupuKopírovat odkaz

Aplikace, kterým jste povolili přístup, najdete v Nastavení > API a webhooky v části Povolené aplikace. Tlačítkem Odebrat přístup aplikace ztratí přístup ke všem vašim účtům. Pro nový přístup ji budete muset znovu povolit.