OAuth 2.1 dla API SpeakNotes

Odkrywanie (Discovery)

Oba dokumenty metadanych są publiczne. Klienci MCP znajdują je automatycznie na podstawie wyzwania 401 zwracanego przez API.

# Authorization server metadata (RFC 8414)
curl https://speaknotes.io/.well-known/oauth-authorization-server

# Protected resource metadata (RFC 9728)
curl https://api.speaknotes.io/.well-known/oauth-protected-resource

Przepływ

1. 1

   Rejestracja klienta

   Wyślij żądanie POST do punktu końcowego rejestracji ze swoimi adresami URI przekierowania. Klienci publiczni używają PKCE i nie otrzymują sekretu; klienci poufni otrzymują go. Akceptowane są schematy https, loopback http oraz niestandardowe schematy aplikacji.

   curl -X POST https://api.speaknotes.io/oauth/register \
     -H "Content-Type: application/json" \
     -d '{
       "client_name": "Your app",
       "redirect_uris": ["https://your.app/callback"],
       "token_endpoint_auth_method": "none",
       "scope": "notes:read notes:write summaries:write"
     }'

2. 2

   Przekierowanie użytkownika do autoryzacji

   Otwórz punkt końcowy autoryzacji, podając client id, redirect URI, zakresy, stan (state) oraz wyzwanie S256 code challenge. Użytkownik loguje się, widzi dokładnie, o jakie zakresy prosisz, i zatwierdza lub odrzuca żądanie.

   https://speaknotes.io/oauth/authorize
     ?client_id=sn_client_...
     &redirect_uri=https://your.app/callback
     &response_type=code
     &scope=notes:read%20summaries:write
     &state=RANDOM
     &code_challenge=BASE64URL_SHA256_OF_VERIFIER
     &code_challenge_method=S256

3. 3

   Wymiana kodu

   Wyślij kod oraz weryfikator kodu (code verifier) do punktu końcowego tokena. Kody są jednorazowe i wygasają po minucie; ponowne użycie kodu powoduje unieważnienie tokenów, które wygenerował.

   curl -X POST https://api.speaknotes.io/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "authorization_code",
       "client_id": "sn_client_...",
       "code": "...",
       "redirect_uri": "https://your.app/callback",
       "code_verifier": "..."
     }'

4. 4

   Odświeżanie

   Tokeny dostępu są ważne przez godzinę. Tokeny odświeżania rotują przy każdym użyciu, a użycie unieważnionego tokena powoduje utratę całego uprawnienia, co zapobiega wykorzystaniu skradzionego tokena.

   curl -X POST https://api.speaknotes.io/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "refresh_token",
       "client_id": "sn_client_...",
       "refresh_token": "sn_rt_..."
     }'

access_token: 1h · refresh_token: 60d, rotating · code: 60s, single use

Żądanie zakresów

Proś tylko o to, co jest absolutnie niezbędne. Odświeżenie może zawęzić zakres, ale nigdy go nie rozszerzyć. Użytkownicy mogą w każdej chwili sprawdzić i cofnąć dostęp aplikacji w swoich ustawieniach.

Unieważnianie

Wyślij żądanie POST z dowolnym tokenem do punktu końcowego unieważniania. Unieważnienie jednego tokena powoduje unieważnienie całej pary. Zgodnie z RFC 7009, unieważnienie nieistniejącego tokena jest traktowane jako sukces.

curl -X POST https://api.speaknotes.io/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"client_id": "sn_client_...", "token": "sn_rt_..."}'