Kenelle tämä on

Rakennat sovellusta (playground, agentti, mobiiliasiakas, …) ja haluat käyttäjiesi liittävän Airforce-tilinsä, jotta he voivat ajaa chattia tai kuvien generointia käyttöliittymäsi kautta jakamatta sinulle raakaa API-avaintaan. Käytä tätä kulkua.

Saat läpinäkymättömän access_token (24h TTL), joka on rajattu siihen, mitä sovelluksesi pyysi ja käyttäjä hyväksyi. Käytä sitä Bearer-otsakkeena /v1/* -päätepisteitä tai /oauth/userinfo.

1. Hanki client_id + client_secret

Phase 1 on ylläpitäjän hallitsema rekisteröinti. Ota meihin yhteyttä ja kerro:

Sovelluksen nimi (näytetään käyttäjillesi suostumusnäytöllä)
Yhden lauseen kuvaus
Etusivun URL (valinnainen, näytetään suostumusnäytöllä)
Neliön muotoinen logo-URL (valinnainen)
Yksi tai useampi tarkka redirect_uri (vain https://, paitsi http://localhost devissä)
Mitä scope-arvoja tarvitset (katso alta)

Lähetämme sinulle takaisin client_id ja kertakäyttöisen client_secret. Säilytä secret palvelinpuolella — jos olet puhdas SPA / natiivisovellus ilman backendia, voit ohittaa secretin ja luottaa pelkkään PKCE:hen.

2. Scope-arvot

Scope	Mitä se myöntää
profile	Lukee user-objektin /oauth/userinfo:n kautta (id, username, plan, liitetyt sähköpostit kun vahvistettu).
chat	POST /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses.
images	POST /v1/images/generations.
keys:read	Varattu — listaa käyttäjän Airforce API -avaimet (Phase 2).
keys:write (ARKALUONTEINEN)	Varattu — luo + peruuttaa käyttäjän Airforce API -avaimet (Phase 2). Arkaluonteinen scope.

Useita scope-arvoja erotetaan välilyönneillä scope -kyselyparametrissa: scope=profile chat images.

3. Kulku

3.1 Luo PKCE-pari

Asiakkaassasi, ennen kuin uudelleenohjaat /oauth/authorize:een, luo satunnainen verifier ja vastaava 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 Uudelleenohjaa /oauth/authorize:een

Rakenna authorize-URL ja lähetä käyttäjä sinne. Hän näkee suostumusnäyttömme, päättää, ja hänet uudelleenohjataan takaisin sinulle.

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

Käyttäjä saapuu suostumusnäyttöömme, kirjautuu sisään (jos ei vielä ole), ja hyväksyy tai hylkää. Uudelleenohjaamme takaisin redirect_uri -osoitteeseesi lyhytikäisellä ?code=… -arvolla hyväksynnän yhteydessä, ?error=access_denied hylkäyksen yhteydessä. Alkuperäinen state palautetaan — varmista, että se täsmää.

3.3 Vaihda code access_tokeniin

Backendistäsi vaihda code (plus PKCE-verifier) access tokeniin.

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"

Vastaus (24h TTL):

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

3.4 Käytä tokenia

Kutsu userinfo-päätepistettä tai mitä tahansa /v1/*-reittiä, jonka myönnetyt scope-arvot sallivat:

# 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-vastaus

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

Kentät kuten email, github_email, discord_username ilmestyvät vain, kun käyttäjä on todella vahvistanut / liittänyt ne. Varaudu sekä läsnäoloon että poissaoloon.

Tokenin peruuttaminen

Kun käyttäjä kirjautuu ulos sovelluksestasi, peruuta token, jotta se ei jatka hänen tilinsä laskutusta taustalla:

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

RFC 7009. Palauttaa aina 200 riippumatta siitä, oliko token olemassa (ei oraakkelia).

Tietoturvahuomiot

PKCE on pakollinen julkisille asiakkaille (ei palvelinpuolen client_secretiä). Hyväksymme vain S256 — code_challenge_method=plain hylätään.
redirect_uri on tarkka osuma. Ei etuliite- / wildcard-osumia. Jos tarvitset useita ympäristöjä, rekisteröi yksi URI per ympäristö.
Tokeneilla on 24h TTL eikä vielä refresh-tokeneita — vanhenemisen yhteydessä aja käyttäjä uudelleen läpi /oauth/authorize -kulun. Pitkäikäisten agenttien osalta kysy käynnistyksessä ja säilytä token turvallisessa tallennustilassa.
Älä säilytä client_secretiä asiakaspuolen koodissa. Jos sovelluksesi on pelkkä selain-SPA tai natiiviasiakas, rekisteröi ilman palvelinta ja luota PKCE:hen.
Käyttäjät voivat peruuttaa sovelluksesi milloin tahansa dashboardistaan → Apps-välilehdeltä. Käsittele 401 ajamalla OAuth-kulku uudelleen.
Phase 1 -kattavuus: OAuth bearer -tokenit toimivat /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/images/generations, ja /oauth/userinfo. Audio-, video-, voice- ja character-päätepisteet vaativat Phase 1:ssä edelleen tavallisen Airforce API -avaimen.

Rekisteröidy

Sähköpostia osoitteeseen [email protected] tai ota meihin yhteyttä Discord yllä luetelluilla rekisteröintitiedoilla. Lähetämme tunnuksesi takaisin muutamassa tunnissa.

Kirjaudu Airforcella