# AI Agent HUB auth.md

> Publiczne dane (API https://aiagenthub.pl/api/v1 i MCP https://aiagenthub.pl/mcp) są dostępne bez logowania. Dane konta użytkownika (https://aiagenthub.pl/mcp/account) wymagają tokenu OAuth 2.1 wydanego przez https://aiagenthub.pl — przez standardowy przepływ kodu z PKCE albo przez rejestrację agenta opisaną niżej.

## Dla kogo

Agenci AI i aplikacje (np. klienci MCP), które w imieniu użytkownika AI Agent HUB chcą odczytać podsumowanie jego konta: plan, saldo kredytów, datę odnowienia i ostatnie użycia narzędzi. Dostęp jest tylko do odczytu — bez płatności i bez zmian na koncie.

## Odkrywanie

- Metadane serwera autoryzacji: https://aiagenthub.pl/.well-known/oauth-authorization-server
- Metadane zasobu: https://aiagenthub.pl/.well-known/oauth-protected-resource/mcp/account
- Klucze: https://aiagenthub.pl/.well-known/jwks.json
- Zakres: `account:read`

## Metoda 1: OAuth 2.1 (klient MCP, aplikacja)

1. Rejestracja klienta (RFC 7591): `POST https://aiagenthub.pl/oauth/register` z `client_name` i `redirect_uris` (https, loopback http albo schemat aplikacji). Tylko klienci publiczni (`token_endpoint_auth_method: none`).
2. `GET https://aiagenthub.pl/oauth/authorize` z `response_type=code`, `client_id`, `redirect_uri`, `scope=account:read`, `state`, `code_challenge` (S256 — obowiązkowe), `resource=https://aiagenthub.pl/mcp/account`.
3. Użytkownik loguje się w AI Agent HUB (z 2FA, jeśli je ma) i zatwierdza dostęp.
4. `POST https://aiagenthub.pl/oauth/token` z `grant_type=authorization_code`, `code`, `code_verifier`, `client_id`, `redirect_uri`.

## Metoda 2: rejestracja agenta (verified e-mail)

Dla agenta bez przeglądarki. Tożsamość potwierdza właściciel konta kodem, po zalogowaniu na konto z tym samym adresem e-mail.

1. `POST https://aiagenthub.pl/agent/identity` (JSON):
   `{"type": "identity_assertion", "assertion_type": "verified_email", "login_hint": "<e-mail konta>", "agent_name": "<nazwa agenta>"}`
   (`"type": "service_auth"` działa tak samo). Odpowiedź: `claim_token` oraz `claim.user_code` i `claim.verification_uri` (https://aiagenthub.pl/polacz/kod), ważne 15 minut.
2. Pokaż użytkownikowi `user_code` i `verification_uri`. Użytkownik loguje się i wpisuje kod.
3. Odpytuj `POST https://aiagenthub.pl/oauth/token` z `grant_type=urn:workos:agent-auth:grant-type:claim` i `claim_token` co 5 sekund. Do zatwierdzenia: `authorization_pending`. Po zatwierdzeniu: `access_token` (1 h) i `refresh_token` (30 dni, rotowany).

## Poświadczenia

- `Authorization: Bearer <access_token>` przy wywołaniach https://aiagenthub.pl/mcp/account.
- Odświeżanie: `grant_type=refresh_token` — każdy refresh token działa raz, odpowiedź zawiera nowy.
- Unieważnienie: `POST https://aiagenthub.pl/oauth/revoke` z `token=<refresh_token>`.
- Przy 401 nagłówek `WWW-Authenticate` wskazuje metadane zasobu.

## Limity

Rejestracja klientów: 20 na godzinę z adresu IP. Rejestracja agentów: 10 na godzinę z adresu IP, 5 na godzinę na adres e-mail. Token: 120 żądań na 10 minut. MCP i API: 120 zapytań na minutę.

## English

Public data needs no credentials. Account data (https://aiagenthub.pl/mcp/account, scope `account:read`) needs an OAuth 2.1 access token issued by https://aiagenthub.pl: either the authorization code flow with PKCE S256 and dynamic client registration, or agent registration — `POST https://aiagenthub.pl/agent/identity` with `login_hint` (the account e-mail), show the returned `user_code` to the user at `https://aiagenthub.pl/polacz/kod`, then poll `https://aiagenthub.pl/oauth/token` with `grant_type=urn:workos:agent-auth:grant-type:claim` and `claim_token`.
