Bu kimin için

Bir uygulama (playground, agent, mobil istemci, …) geliştiriyorsun ve kullanıcılarının Airforce hesaplarını bağlayarak ham API anahtarını seninle paylaşmadan arayüzün üzerinden chat veya görsel üretimi çalıştırmasını istiyorsun. Bu akışı kullan.

Opak bir access_token alacaksın (24h TTL), uygulamanın talep ettiği ve kullanıcının onayladığı şeyle sınırlı. Bunu /v1/* endpoint'lerine veya /oauth/userinfo.

1. client_id + client_secret edin

Phase 1, admin tarafından yönetilen bir kayıttır. Bize şunlarla yaz:

Uygulama adı (kullanıcılarına onay ekranında gösterilir)
Tek cümlelik açıklama
Anasayfa URL'si (isteğe bağlı, onay ekranında gösterilir)
Kare logo URL'si (isteğe bağlı)
Bir veya daha fazla tam redirect_uri (yalnızca https://, dev için http://localhost hariç)
İhtiyacın olan scope'lar (aşağıya bak)

Sana geri göndeririz client_id ve tek seferlik client_secret. Secret'ı sunucu tarafında sakla — saf bir SPA / native uygulama olup backend'in yoksa secret'ı atlayıp yalnızca PKCE'ye güvenebilirsin.

2. Scope'lar

Scope	Ne sağlar
profile	/oauth/userinfo üzerinden user objesini okur (id, username, plan, doğrulandığında bağlı emailler).
chat	POST /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses.
images	POST /v1/images/generations.
keys:read	Rezervedir — kullanıcının Airforce API anahtarlarını listeler (Phase 2).
keys:write (HASSAS)	Rezervedir — kullanıcının Airforce API anahtarlarını oluşturur + iptal eder (Phase 2). Hassas scope.

Birden fazla scope, boşlukla ayrılır ve scope sorgu parametresinde belirtilir: scope=profile chat images.

3. Akış

3.1 PKCE çifti üret

İstemcinde, /oauth/authorize'a yönlendirmeden önce rastgele bir verifier ve eşleşen SHA-256 challenge üret.

// 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 /oauth/authorize'a yönlendir

Authorize URL'ini oluştur ve kullanıcıyı oraya gönder. Onay ekranımızı görür, karar verir ve sana geri yönlendirilir.

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

Kullanıcı onay ekranımıza gelir, oturum açar (henüz açmadıysa) ve onaylar veya reddeder. Onayda kısa ömürlü bir redirect_uri ile ?code=… adresine geri yönlendiririz, ?error=access_denied reddederse. Orijinal state değerin geri gönderilir — eşleştiğini doğrula.

3.3 Code'u access_token ile takas et

Backend'inden code'u (artı PKCE verifier'ı) bir access token ile takas et.

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"

Yanıt (24h TTL):

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

3.4 Token'ı kullan

Userinfo endpoint'ini veya verilen scope'ların izin verdiği herhangi bir /v1/* rotasını çağır:

# 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 yanıtı

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

Şunun gibi alanlar email, github_email, discord_username yalnızca kullanıcı gerçekten doğruladığında / bağladığında görünür. Hem varlık hem yokluk için plan yap.

Token iptal etme

Bir kullanıcı uygulamandan çıkış yaptığında, arka planda hesabını faturalandırmaya devam etmemesi için token'ı iptal et:

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

RFC 7009. Token'ın var olup olmadığına bakılmaksızın daima 200 döndürür (oracle yok).

Güvenlik notları

PKCE, public client'lar için zorunludur (sunucu tarafı client_secret yok). Yalnızca S256 kabul ediyoruz — code_challenge_method=plain reddedilir.
redirect_uri tam eşleşmedir. Prefix / wildcard eşleşmesi yok. Birden fazla ortama ihtiyacın varsa, her ortam için bir URI kaydet.
Token'ların 24h TTL'si vardır ve henüz refresh token yoktur — süresi dolduğunda kullanıcıyı tekrar /oauth/authorize akışından geçir. Uzun süreli agent'lar için başlangıçta sor ve token'ı güvenli depolamada sakla.
client_secret'ı istemci tarafı kodda saklama. Uygulaman yalnızca tarayıcı SPA'sı veya native istemciyse, sunucusuz kaydol ve PKCE'ye güven.
Kullanıcılar uygulamanı dashboard → Apps sekmesinden istedikleri zaman iptal edebilir. 401'i, OAuth akışını yeniden çalıştırarak ele al.
Phase 1 kapsamı: OAuth bearer token'lar /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/images/generations, ve /oauth/userinfo. Audio, video, voice ve character endpoint'leri Phase 1'de hâlâ normal bir Airforce API anahtarı gerektirir.

Kayıt ol

Email [email protected] veya bize şuradan ulaş Discord yukarıda listelenen kayıt bilgileriyle. Kimlik bilgilerini birkaç saat içinde geri göndereceğiz.

Airforce ile oturum aç