Mit Airforce anmelden

Für wen das gedacht ist

Du baust eine App (Playground, Agent, Mobile Client, …) und willst, dass deine Nutzer ihr Airforce-Konto einbinden, damit sie Chat oder Bildgenerierung über deine UI nutzen können, ohne dir ihren API-Key zu geben. Nutze diesen Flow.

Du bekommst ein opakes access_token (24h TTL), eingeschränkt auf das, was deine App angefragt und der Nutzer freigegeben hat. Verwende es als Bearer-Header gegen /v1/* -Endpoints oder /oauth/userinfo.

1. client_id + client_secret bekommen

In Phase 1 ist die Registrierung admin-verwaltet. Schreib uns mit folgenden Angaben:

• App-Name (wird Nutzern auf dem Consent-Screen angezeigt)
• Ein-Satz-Beschreibung
• Homepage-URL (optional, erscheint im Consent)
• Quadratisches Logo-URL (optional)
• Eine oder mehrere exakte Redirect-URIs (nur https://, außer http://localhost für Dev)
• Welche Scopes du brauchst (siehe unten)

Wir schicken dir client_id und ein einmaliges client_secret. Bewahre das Secret serverseitig auf — wenn deine App eine reine SPA / Native App ohne Backend ist, kannst du das Secret weglassen und nur auf PKCE vertrauen.

2. Scopes

Mehrere Scopes werden mit Leerzeichen getrennt im scope -Query-Parameter angegeben: scope=profile chat images.

3. Der Flow

3.1 PKCE-Paar erzeugen

Erzeuge in deinem Client vor dem Weiterleiten auf /oauth/authorize einen zufälligen Verifier und die passende 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 Auf /oauth/authorize weiterleiten

Bau die Authorize-URL und schick den Nutzer hin. Er sieht unseren Consent-Screen, entscheidet, und wird zu dir zurückgeleitet.

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

Der Nutzer landet auf unserem Consent-Screen, meldet sich an (falls noch nicht) und gibt frei oder verweigert. Wir leiten zurück an deine redirect_uri mit einem kurzlebigen ?code=… bei Zustimmung, ?error=access_denied bei Ablehnung. Dein ursprünglicher state kommt zurück — prüfe, dass er übereinstimmt.

3.3 Code gegen access_token tauschen

Tausche aus deinem Backend den Code (plus PKCE-Verifier) gegen einen 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"

Antwort (24h TTL):

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

3.4 Den Token verwenden

Ruf den Userinfo-Endpoint oder eine /v1/*-Route auf, die die gewährten Scopes abdecken:

# 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"}]}'

/oauth/userinfo-Antwort

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

Felder wie email, github_email, discord_username erscheinen nur, wenn der Nutzer sie verifiziert / verknüpft hat. Plane für Anwesenheit und Abwesenheit.

Token widerrufen

Wenn sich ein Nutzer aus deiner App ausloggt, widerrufe den Token, damit er nicht im Hintergrund weiter sein Konto belastet:

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

RFC 7009. Gibt immer 200 zurück, egal ob der Token existierte (kein Oracle).

Sicherheitshinweise

• PKCE ist Pflicht für Public Clients (kein serverseitiges client_secret). Wir akzeptieren nur S256 — code_challenge_method=plain wird abgelehnt.
• redirect_uri ist Exact-Match. Kein Prefix / Wildcard. Wenn du mehrere Umgebungen brauchst, registriere eine URI pro Umgebung.
• Tokens haben eine 24h-TTL und noch keine Refresh-Tokens — bei Ablauf schick den Nutzer erneut durch /oauth/authorize . Für langlaufende Agents: beim Start abfragen und den Token in sicherem Speicher ablegen.
• Speichere client_secret nicht in Client-Code. Wenn deine App eine reine Browser-SPA oder ein Native-Client ist, registriere ohne Server und vertrau auf PKCE.
• Nutzer können deine App jederzeit aus ihrem Dashboard → Apps-Tab widerrufen. Reagiere auf 401, indem du den OAuth-Flow neu startest.
• Phase-1-Abdeckung: OAuth-Bearer-Tokens funktionieren auf /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/images/generations, und /oauth/userinfo. Audio-, Video-, Voice- und Character-Endpoints brauchen in Phase 1 weiterhin einen normalen Airforce-API-Key.

Registrieren

E-Mail an [email protected] oder schreib uns auf Discord mit den oben genannten Registrierungsdetails. Du bekommst deine Zugangsdaten innerhalb weniger Stunden zurück.