# Konto w Teście auth.md > Dane o bankach (indeks, dostępność, przerwy KIR, aplikacje, decyzje UOKiK) są publiczne: REST API i serwer MCP działają bez rejestracji i bez tokenu. Logowanie (OAuth 2.1) jest potrzebne tylko do osobistych alertów e-mail czytelnika o awariach banków. ## Dla kogo Agenci AI i klienci MCP działający w imieniu konkretnego czytelnika Konta w Teście (kontowtescie.pl), który chce, żeby agent sprawdzał, włączał i wyłączał jego alerty e-mail o awariach stron logowania banków. Do samych danych nie rejestruj się – wywołuj narzędzia publiczne bez nagłówka `Authorization`. ## Co wymaga tokenu Serwer MCP : | Narzędzie | Scope | Co robi | |---|---|---| | `list_my_alerts` | `alerts:read` | czy alerty są włączone i dla których banków | | `add_alert` (`bank`) | `alerts:write` | dodaje bank do alertów: e-mail, gdy strona logowania banku nie odpowiada w 2 kolejnych sprawdzeniach co 5 minut, i drugi, gdy znowu działa | | `remove_alert` (`bank`) | `alerts:write` | usuwa bank z alertów | Wywołanie tych narzędzi bez tokenu daje `HTTP 401` z nagłówkiem `WWW-Authenticate: Bearer resource_metadata="https://kontowtescie.pl/.well-known/oauth-protected-resource/mcp", scope="alerts:read alerts:write"`. Token z za wąskim zakresem: `HTTP 403`, `error="insufficient_scope"`. `alerts:write` dostaniesz tylko wtedy, gdy czytelnik ma włączone alerty albo zaznaczy zgodę na e-maile z alertami na ekranie zgody (inaczej dostaniesz tylko `alerts:read`). ## Odkrywanie 1. Metadane zasobu (RFC 9728): (zasób ) albo (cały serwis). 2. Metadane serwera autoryzacji (RFC 8414): – issuer , blok `agent_auth`, klucze JWKS . ## Rejestracja Dwie metody. Obie kończą się tym samym: token dostępu do po zalogowaniu czytelnika linkiem z e-maila i jego zgodzie. Nie ma haseł ani kluczy API. ### 1. OAuth 2.1 z dynamiczną rejestracją (klienci MCP) 1. `POST` (RFC 7591, JSON): `redirect_uris` (https albo /`localhost`/`[::1]` dla aplikacji natywnych; port loopback może się zmieniać), `client_name`, `token_endpoint_auth_method` (`none` dla klientów publicznych, albo `client_secret_basic`/`client_secret_post`), `grant_types: ["authorization_code","refresh_token"]`. Odpowiedź `201` z `client_id` (i `client_secret`, jeśli klient poufny). 2. Przeglądarka: `GET` – PKCE S256 obowiązkowe, `redirect_uri` dokładnie jak przy rejestracji. 3. Czytelnik podaje e-mail, klika link (albo wpisuje 6-cyfrowy kod) i na ekranie zgody widzi nazwę klienta, adres powrotu, zakresy i zasób. 4. Powrót: `redirect_uri?code=…&state=…&iss=` (sprawdź `state` i `iss`). Kod działa 3 minuty, raz. 5. `POST` (`application/x-www-form-urlencoded`): `grant_type=authorization_code&code=…&redirect_uri=…&code_verifier=…&client_id=…&resource=` . ### 2. Rejestracja agenta (auth.md, `service_auth`) Gdy agent zna tylko e-mail czytelnika i nie ma przeglądarki z przekierowaniem: 1. `POST` (JSON) `{"type":"service_auth","login_hint":"czytelnik@example.com","client_name":"Nazwa agenta"}`. Przyjmujemy też starszy kształt `{"type":"identity_assertion","assertion_type":"verified_email","assertion":"czytelnik@example.com"}`. Odpowiedź `200`: `registration_id`, `claim_token` (zwracany raz, trzymaj w pamięci), `claim_token_expires` (1 h), `post_claim_scopes`, `claim` = `user_code` (6 cyfr), `verification_uri`, `expires_in` (600), `interval` (5). 2. Pokaż czytelnikowi w jednej wiadomości `verification_uri` i `user_code`. Czytelnik otwiera link, loguje się linkiem z e-maila wysłanym na podany adres, sprawdza, o co prosisz, i wpisuje `user_code` na naszej stronie (nie odsyła go Tobie). 3. Odpytuj `POST` z `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=…` nie częściej niż co `interval` sekund. Odpowiedzi: `authorization_pending`, `slow_down`, `expired_token` (nowy kod: `POST` z `{"claim_token":"…","email":"…"}`), `access_denied` (czytelnik odmówił), a po zgodzie standardowa odpowiedź tokenu z `access_token`, `refresh_token`, `scope` i `client_id`. ## Poświadczenia - `Authorization: Bearer ` w każdym żądaniu do . Nigdy w adresie URL. - Access token: JWT RS256 (`typ: at+jwt`), ważny 3600 s, `aud` = zasób, o który prosiłeś (`resource`). Na innym zasobie nie działa. - Odświeżanie: `grant_type=refresh_token&refresh_token=…` (+ `client_id`/sekret klienta). Każde użycie daje nowy refresh token; ponowne użycie starego unieważnia cały łańcuch. Refresh token żyje 30 dni od ostatniego użycia, łańcuch najwyżej 90 dni – potem czytelnik loguje się ponownie. - Na `HTTP 401` z `error="invalid_token"` odśwież token raz; jeśli `invalid_grant`, zacznij od rejestracji. ## Odwołanie - Agent: `POST` (RFC 7009) `token=…&token_type_hint=refresh_token` – odwołanie refresh tokenu kończy cały łańcuch. Zawsze `200`. - Czytelnik: strona „Twoje połączone aplikacje” https://kontowtescie.pl/oauth/aplikacje/ (link przychodzi też w e-mailu po każdym nowym połączeniu). Odwołanie działa od razu, także dla wydanych access tokenów. Same alerty wyłącza link w każdym e-mailu z alertem. ## Limity Serwer MCP i REST: 60 zapytań na minutę z jednego IP (`429`, `Retry-After`). Rejestracje: 10 na godzinę z IP. E-maile logowania: 3 na 15 minut na adres. Token: 60 zapytań na minutę z IP. Kod z e-maila i `user_code`: 5 prób. Zmiany alertów: 30 na dobę na konto. ## Dane i prywatność Przechowujemy adres e-mail czytelnika, nazwę klienta, zakresy i daty zgody. Tokeny, kody i linki tylko jako skróty HMAC. Dziennik bezpieczeństwa bez adresów e-mail i IP w jawnej postaci, 90 dni. Szczegóły: https://kontowtescie.pl/polityka-prywatnosci/ (sekcje o alertach i połączonych aplikacjach). Dokumentacja: https://kontowtescie.pl/dla-agentow/. Kontakt: redakcja@kontowtescie.pl. ## English Bank data is public: call the MCP server (https://kontowtescie.pl/mcp) without credentials. Only the reader's own outage-alert tools (`list_my_alerts`, `add_alert`, `remove_alert`; scopes `alerts:read`, `alerts:write`) need an OAuth 2.1 access token from https://kontowtescie.pl. Either register a client (RFC 7591, ) and run the authorization code flow with PKCE S256 and `resource=` , or register as an agent with `POST https://kontowtescie.pl/oauth/agent/identity {"type":"service_auth","login_hint":""}`, show the reader `verification_uri` + `user_code`, and poll with `grant_type=urn:workos:agent-auth:grant-type:claim`. The reader signs in with an e-mail link (no passwords) and approves on a consent screen. Access tokens last 3600 s; refresh tokens rotate (reuse revokes the chain). Revoke at ; readers manage access at https://kontowtescie.pl/oauth/aplikacje/.