Dla kogo to jest

Budujesz aplikację (playground, agent, klient mobilny, …) i chcesz, by Twoi użytkownicy podpięli swoje konto Airforce, by mogli uruchamiać chat lub generowanie obrazów przez Twój interfejs bez udostępniania Ci surowego API key. Użyj tego przepływu.

Dostaniesz nieprzezroczysty access_token (24h TTL) ograniczony do tego, o co poprosiła Twoja aplikacja i co użytkownik zatwierdził. Użyj go jako nagłówka Bearer wobec endpointów /v1/* lub /oauth/userinfo.

1. Uzyskaj client_id + client_secret

Faza 1 to rejestracja zarządzana przez administratora. Napisz do nas z:

Nazwa aplikacji (pokazywana na ekranie zgody Twoim użytkownikom)
Opis w jednym zdaniu
URL strony głównej (opcjonalnie, pokazywany na ekranie zgody)
URL kwadratowego logo (opcjonalnie)
Jeden lub więcej dokładnych redirect_uri (tylko https://, z wyjątkiem http://localhost dla dev)
Jakich scope'ów potrzebujesz (zobacz poniżej)

Odsyłamy Ci client_id i jednorazowy client_secret. Przechowuj secret po stronie serwera — jeśli jesteś czystym SPA / aplikacją natywną bez backendu, możesz pominąć secret i polegać tylko na PKCE.

2. Scope'y

Scope	Co przyznaje
profile	Czyta obiekt user przez /oauth/userinfo (id, username, plan, powiązane emaile gdy zweryfikowane).
chat	POST /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses.
images	POST /v1/images/generations.
keys:read	Zarezerwowane — lista kluczy API Airforce użytkownika (Phase 2).
keys:write (WRAŻLIWY)	Zarezerwowane — tworzy + odwołuje klucze API Airforce użytkownika (Phase 2). Wrażliwy scope.

Wiele scope'ów oddzielonych jest spacjami w parametrze zapytania scope : scope=profile chat images.

3. Przepływ

3.1 Wygeneruj parę PKCE

W swoim kliencie, przed przekierowaniem na /oauth/authorize, wygeneruj losowy verifier i pasujący SHA-256 challenge.

// In your app, before redirecting to /oauth/authorize:
const verifier = randomString(64); // 43..128 chars [A-Z][a-z][0-9]-._~
const challenge = base64UrlNoPad(sha256(verifier));
sessionStorage.setItem('airforce_pkce_verifier', verifier);

3.2 Przekieruj na /oauth/authorize

Zbuduj URL autoryzacji i wyślij tam użytkownika. Zobaczy nasz ekran zgody, zdecyduje i zostanie przekierowany z powrotem do Ciebie.

https://api.airforce/oauth/authorize?
  response_type=code
  &client_id=airforce_xxxxxxxxxxxxxxxxxxxxxxxxx
  &redirect_uri=https://your.app/oauth/callback
  &scope=profile chat
  &state=<random opaque>
  &code_challenge=<base64url(sha256(verifier))>
  &code_challenge_method=S256

Użytkownik trafia na nasz ekran zgody, loguje się (jeśli jeszcze nie), i zatwierdza lub odrzuca. Przekierowujemy z powrotem na Twoje redirect_uri z krótkotrwałym ?code=… przy zatwierdzeniu, ?error=access_denied przy odrzuceniu. Twoje oryginalne state jest zwracane — sprawdź, czy się zgadza.

3.3 Wymień code na access_token

Z Twojego backendu wymień code (plus PKCE verifier) na access token.

curl -X POST https://api.airforce/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "redirect_uri=https://your.app/oauth/callback" \
  --data-urlencode "code_verifier=$VERIFIER"

Odpowiedź (24h TTL):

{
  "access_token": "airf_oat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "profile chat"
}

3.4 Użyj tokena

Wywołaj endpoint userinfo lub dowolną trasę /v1/*, na którą pozwalają przyznane scope'y:

# Profile lookup
curl https://api.airforce/oauth/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Chat (requires scope=chat)
curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hi"}]}'

Odpowiedź /oauth/userinfo

{
  "id": "user-uuid",
  "username": "foo",
  "plan": "free",
  "is_admin": false,
  "email": "[email protected]",
  "email_verified": true,
  "github_email": "[email protected]",
  "discord_username": "foo#1234"
}

Pola takie jak email, github_email, discord_username pojawiają się tylko, gdy użytkownik je faktycznie zweryfikował / powiązał. Planuj zarówno na obecność, jak i nieobecność.

Odwołanie tokena

Gdy użytkownik wyloguje się z Twojej aplikacji, odwołaj token, by nie obciążał dalej jego konta w tle:

curl -X POST https://api.airforce/oauth/revoke \
  --data-urlencode "token=$ACCESS_TOKEN"

RFC 7009. Zawsze zwraca 200 niezależnie od tego, czy token istniał (brak oracle).

Uwagi bezpieczeństwa

PKCE jest obowiązkowe dla klientów publicznych (brak client_secret po stronie serwera). Akceptujemy tylko S256 — code_challenge_method=plain jest odrzucane.
redirect_uri działa na dokładne dopasowanie. Brak dopasowania po prefiksie / wildcard. Jeśli potrzebujesz wielu środowisk, zarejestruj jeden URI na środowisko.
Tokeny mają 24h TTL i nie ma jeszcze refresh tokenów — po wygaśnięciu, przepuść użytkownika przez /oauth/authorize ponownie. Dla agentów długo żyjących, pytaj przy starcie i przechowuj token w bezpiecznym miejscu.
Nie przechowuj client_secret w kodzie po stronie klienta. Jeśli Twoja aplikacja to czyste SPA przeglądarkowe lub klient natywny, zarejestruj się bez serwera i polegaj na PKCE.
Użytkownicy mogą odwołać Twoją aplikację w dowolnej chwili z ich panelu → zakładka Apps. Obsłuż 401 ponownie uruchamiając przepływ OAuth.
Pokrycie Fazy 1: Tokeny OAuth bearer działają na /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/images/generations, i /oauth/userinfo. Endpointy audio, wideo, voice i character w Fazie 1 nadal wymagają zwykłego klucza API Airforce.

Zarejestruj się

Email na [email protected] lub napisz do nas na Discord z danymi rejestracyjnymi wymienionymi powyżej. Odeślemy Twoje dane logowania w ciągu kilku godzin.

Zaloguj z Airforce