# Centrum Finansowe auth.md

> Agenci AI działają w Centrum Finansowe AI Agent HUB wyłącznie w imieniu istniejącego konta i z jego uprawnieniami.
> Dostęp daje właściciel konta: logowaniem OAuth, kluczem API z panelu albo kodem potwierdzającym rejestrację agenta.

## Dla kogo

Asystenci i agenci (Claude, Hermes, ChatGPT, własne automaty), którzy mają obsługiwać faktury, KSeF,
koszty, kontrahentów i ustawienia firm użytkownika. Jedno konto może prowadzić wiele firm.

## Metody

1. **OAuth 2.1 (zalecane dla klientów z przeglądarką).** Zasób: `https://ksiegowosc.aiagenthub.pl/mcp`.
   Metadane zasobu: https://ksiegowosc.aiagenthub.pl/.well-known/oauth-protected-resource/mcp. Serwer autoryzacji: https://ekuxswlfswacpfetyfsh.supabase.co/auth/v1
   (kod autoryzacji + PKCE S256, dynamiczna rejestracja klienta). Użytkownik loguje się i zatwierdza dostęp
   na https://ksiegowosc.aiagenthub.pl/oauth/consent.
2. **Klucz API.** Właściciel tworzy go w panelu (https://ksiegowosc.aiagenthub.pl/dashboard/agents), wybiera firmy i zakres
   (odczyt albo odczyt i zmiany), może go w każdej chwili cofnąć. Użycie: `Authorization: Bearer cfa_…`.
3. **Rejestracja agenta (service_auth, e-mail potwierdzany kodem).** Opis niżej.

## Rejestracja agenta

Serwer autoryzacji: https://ksiegowosc.aiagenthub.pl — metadane: https://ksiegowosc.aiagenthub.pl/.well-known/oauth-authorization-server (blok `agent_auth`).

1. `POST https://ksiegowosc.aiagenthub.pl/oauth/agent/identity` z JSON
   `{"type": "service_auth", "login_hint": "<e-mail właściciela konta>", "agent_name": "<nazwa agenta>"}`.
   Odpowiedź: `claim_token`, `claim.user_code` (6 cyfr), `claim.verification_uri_complete`, `claim.interval`.
   Starszy kształt `{"type": "identity_assertion", "assertion_type": "verified_email", "assertion": "<e-mail>"}`
   jest obsługiwany tak samo — adres i tak potwierdza właściciel kodem.
2. Pokaż właścicielowi konta kod i link. Właściciel loguje się na konto z tym adresem e-mail, wpisuje kod
   i wybiera firmy oraz zakres dostępu.
3. Co `interval` sekund: `POST https://ksiegowosc.aiagenthub.pl/oauth/token` z
   `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<claim_token>`. Do potwierdzenia odpowiedź to
   `authorization_pending`; potem `access_token` (JWT, 60 min) i `refresh_token`.
4. Odnawianie: `grant_type=refresh_token&refresh_token=<cfr_…>` (token rotowany przy każdym użyciu).
5. Kod wygasa po 10 minutach — nowy: `POST https://ksiegowosc.aiagenthub.pl/oauth/agent/claim`
   z `claim_token` i tym samym `email`. Rejestracja jest ważna 24 godziny.

Odpowiedź rejestracji nie zdradza, czy konto istnieje, a serwer nie wysyła żadnych e-maili.

## Poświadczenia

- Token wysyłaj wyłącznie w nagłówku `Authorization: Bearer …`.
- Klucz API i refresh token przechowuj jak hasło. Unieważnienie: `POST https://ksiegowosc.aiagenthub.pl/oauth/revoke` z `token=…`
  albo w panelu.
- Agent nie zmienia hasła, e-maila ani 2FA konta i nie ma dostępu do funkcji administracyjnych.

## Zasoby

- MCP: https://ksiegowosc.aiagenthub.pl/mcp (karta: https://ksiegowosc.aiagenthub.pl/.well-known/mcp/server-card.json)
- REST: https://ksiegowosc.aiagenthub.pl/api/v1 (OpenAPI: https://ksiegowosc.aiagenthub.pl/openapi.json)
- Instrukcja dla agentów: https://ksiegowosc.aiagenthub.pl/.well-known/agent-skills/centrum-finansowe/SKILL.md
- Dokumentacja: https://ksiegowosc.aiagenthub.pl/dla-agentow

## Limity

120 wywołań na minutę na konto; 10 rejestracji agentów na godzinę z jednego adresu IP.

## English

Agents act only for an existing Centrum Finansowe AI Agent HUB account, with that account's permissions, across all of its
companies (or the companies selected for an API key). Use OAuth 2.1 against https://ksiegowosc.aiagenthub.pl/mcp, a panel API key
(`Bearer cfa_…`), or the registration above: POST the owner's e-mail to https://ksiegowosc.aiagenthub.pl/oauth/agent/identity, show them
the 6-digit code, and poll https://ksiegowosc.aiagenthub.pl/oauth/token with the claim grant until they confirm it in the panel.
