Accedi con Airforce

A chi è rivolto

Stai costruendo un'app (playground, agente, client mobile, …) e vuoi che i tuoi utenti colleghino il loro account Airforce così possono eseguire chat o generazione di immagini tramite la tua UI senza condividere la loro API key grezza con te. Usa questo flusso.

Otterrai un access_token opaco (24h TTL) limitato a ciò che la tua app ha richiesto e che l'utente ha approvato. Usalo come header Bearer contro gli endpoint /v1/* o /oauth/userinfo.

1. Ottieni un client_id + client_secret

La Fase 1 è una registrazione gestita dall'admin. Scrivici con:

• Nome dell'app (mostrato sullo schermo di consenso ai tuoi utenti)
• Descrizione di una frase
• URL della homepage (opzionale, mostrato nel consenso)
• URL del logo quadrato (opzionale)
• Una o più redirect_uri esatte (solo https://, eccetto http://localhost per il dev)
• Quali scope ti servono (vedi sotto)

Ti rispediamo client_id e un client_secret. Conserva il secret lato server — se sei una pura SPA / app nativa senza backend, puoi saltare il secret e affidarti solo a PKCE.

2. Scope

Più scope sono separati da spazi nel parametro di query scope : scope=profile chat images.

3. Il flusso

3.1 Genera coppia PKCE

Nel tuo client, prima di reindirizzare a /oauth/authorize, genera un verifier casuale e il challenge SHA-256 corrispondente.

// 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 Reindirizza a /oauth/authorize

Costruisci l'URL di autorizzazione e manda l'utente lì. Vedrà il nostro consent screen, deciderà, e sarà reindirizzato da te.

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

L'utente arriva sul nostro consent screen, fa il login (se non già), e approva o rifiuta. Reindirizziamo al tuo redirect_uri con un ?code=… di breve durata in caso di approvazione, ?error=access_denied in caso di rifiuto. Il tuo state originale viene rispedito — verifica che corrisponda.

3.3 Scambia il code per access_token

Dal tuo backend, scambia il code (più il verifier PKCE) per un 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"

Risposta (24h TTL):

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

3.4 Usa il token

Chiama l'endpoint userinfo o qualsiasi route /v1/* permessa dagli scope concessi:

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

Risposta di /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"
}

Campi come email, github_email, discord_username appaiono solo quando l'utente li ha effettivamente verificati / collegati. Prevedi sia la presenza che l'assenza.

Revocare un token

Quando un utente esce dalla tua app, revoca il token così non continua a fatturare il suo account in background:

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

RFC 7009. Restituisce sempre 200 indipendentemente dal fatto che il token esistesse (nessun oracle).

Note di sicurezza

• PKCE è obbligatorio per i client pubblici (nessun client_secret lato server). Accettiamo solo S256 — code_challenge_method=plain viene rifiutato.
• redirect_uri è exact-match. Nessun prefix / wildcard matching. Se ti servono più ambienti, registra una URI per ambiente.
• I token hanno un TTL di 24h e ancora nessun refresh token — alla scadenza, fai ripassare l'utente per /oauth/authorize di nuovo. Per agenti a lunga durata, chiedi all'avvio e conserva il token in uno storage sicuro.
• Non memorizzare client_secret nel codice client. Se la tua app è una SPA solo browser o un client nativo, registrati senza server e affidati a PKCE.
• Gli utenti possono revocare la tua app in qualsiasi momento dalla loro dashboard → scheda Apps. Gestisci il 401 ripetendo il flusso OAuth.
• Copertura Fase 1: I bearer token OAuth funzionano su /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/images/generations, e /oauth/userinfo. Gli endpoint audio, video, voice e character richiedono ancora una normale API key Airforce in Fase 1.

Registrati

Email a [email protected] o contattaci su Discord con i dettagli di registrazione elencati sopra. Riceverai le tue credenziali in poche ore.