OAuth 2.1

OAuth 2.1 pozwala użytkownikom logować się do Twojej aplikacji kontem Hypris i nadawać jej dostęp bez dzielenia się hasłem ani kluczem. Tak samo łączą się asystenci AI przez MCP. Hypris obsługuje przepływ authorization code z PKCE i odświeżanie tokenów.

Najważniejsze fakty

Odkrywanie serwera

Nie wpisuj adresów na sztywno. Metadane serwera autoryzacji są pod standardowym adresem, w domenie API, ale poza ścieżką wersji:

https://api.staging.hypris.com/.well-known/oauth-authorization-server

Znajdziesz w nich authorization_endpoint, token_endpoint, registration_endpoint, revocation_endpoint i listę zakresów w scopes_supported. Serwer MCP publikuje dodatkowo /.well-known/oauth-protected-resource, dzięki czemu klienci MCP odnajdują serwer autoryzacji bez żadnej konfiguracji.

Rejestracja klienta

Masz dwie możliwości:

• Client ID Metadata Document. Jako client_id podajesz adres HTTPS dokumentu JSON z opisem aplikacji. Hypris pobierze go sam, więc nie musisz niczego rejestrować.

• Dynamiczna rejestracja. Wyślij POST https://api.staging.hypris.com/v1/oauth/register z client_name, redirect_uris i opcjonalnie token_endpoint_auth_method. Endpoint nie wymaga logowania, ale ma limit 10 rejestracji na godzinę z jednego adresu IP.

Przepływ krok po kroku

1. Wygeneruj losowy code_verifier i policz z niego code_challenge jako base64url z SHA-256.

2. Przekieruj użytkownika na authorization_endpoint z parametrami response_type=code, client_id, redirect_uri, scope, state, code_challenge i code_challenge_method=S256.

3. Użytkownik loguje się, wybiera workspace i potwierdza zakresy na ekranie zgody.

4. Hypris przekierowuje z powrotem na redirect_uri z parametrami code i state. Sprawdź, czy state się zgadza.

5. Wymień kod na tokeny w token_endpoint.

curl -X POST "https://api.staging.hypris.com/v1/oauth/token" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://twoja-aplikacja.pl/callback" \
  -d client_id="$CLIENT_ID" \
  -d code_verifier="$CODE_VERIFIER"

Klient poufny dokłada swój sekret w nagłówku Basic albo w polu client_secret, zgodnie z metodą wybraną przy rejestracji.

Odświeżanie tokenu

curl -X POST "https://api.staging.hypris.com/v1/oauth/token" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN" \
  -d client_id="$CLIENT_ID"

Odpowiedź zawiera nową parę tokenów. Zawsze zapisuj nowy refresh_token w miejsce starego.

Unieważnienie tokenu

curl -X POST "https://api.staging.hypris.com/v1/oauth/revoke" \
  -d token="$REFRESH_TOKEN"

Użytkownik może też odebrać dostęp sam, w ustawieniach konta, w sekcji Autoryzowane aplikacje.

Zakresy

Gdy nie podasz scope, aplikacja dostaje tylko zakresy wymagane. Zakresy oddzielasz spacją.

Co widzi aplikacja

Token jest przypisany do workspace wybranego na ekranie zgody i nie sięgnie do innego. W tym workspace aplikacja widzi przecięcie dwóch zbiorów: uprawnień użytkownika i uprawnień, które administrator nadał aplikacji. Nie zobaczy niczego, czego nie widzi użytkownik.

Błędy

Endpointy OAuth zwracają błędy w formacie z RFC 6749, a nie w zwykłej kopercie API:

{
  "error": "invalid_grant",
  "error_description": "…"
}

Najczęstsze kody to invalid_client, invalid_grant, invalid_scope, unauthorized_client i unsupported_grant_type.