यह किसके लिए है

आप एक ऐप (playground, agent, mobile client, …) बना रहे हैं और चाहते हैं कि आपके उपयोगकर्ता अपना Airforce अकाउंट प्लग-इन करें ताकि वे अपनी raw API key आपके साथ साझा किए बिना आपके UI के माध्यम से chat या image generation चला सकें। इस flow का उपयोग करें।

आपको एक opaque access_token मिलेगा (24h TTL) जो आपके ऐप द्वारा अनुरोधित और उपयोगकर्ता द्वारा अनुमोदित scope तक सीमित है। इसे Bearer header के रूप में /v1/* endpoints या /oauth/userinfo.

1. client_id + client_secret प्राप्त करें

Phase 1 admin-प्रबंधित registration है। हमें इनके साथ ping करें:

ऐप नाम (आपके उपयोगकर्ताओं को consent screen पर दिखाया जाता है)
एक-वाक्य का विवरण
Homepage URL (वैकल्पिक, consent पर दिखाया जाता है)
वर्गाकार logo URL (वैकल्पिक)
एक या अधिक सटीक redirect_uri (केवल https://, dev के लिए http://localhost को छोड़कर)
आपको किन scopes की आवश्यकता है (नीचे देखें)

हम आपको वापस भेजते हैं client_id और एक one-time client_secret. secret को server-side store करें — यदि आप एक शुद्ध SPA / native ऐप हैं जिसमें कोई backend नहीं है, तो आप secret को छोड़ सकते हैं और केवल PKCE पर भरोसा कर सकते हैं।

2. Scopes

Scope	यह क्या देता है
profile	/oauth/userinfo के माध्यम से user object को पढ़ता है (id, username, plan, verified होने पर linked emails)।
chat	POST /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses.
images	POST /v1/images/generations.
keys:read	Reserved — उपयोगकर्ता की Airforce API keys को सूचीबद्ध करता है (Phase 2)।
keys:write (संवेदनशील)	Reserved — उपयोगकर्ता की Airforce API keys बनाता + revoke करता है (Phase 2)। संवेदनशील scope।

एकाधिक scopes को scope query parameter में space से अलग किया जाता है: scope=profile chat images.

3. Flow

3.1 PKCE जोड़ी उत्पन्न करें

अपने client में, /oauth/authorize पर redirect करने से पहले, एक random verifier और मेल खाता 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 /oauth/authorize पर redirect करें

authorize URL बनाएं और उपयोगकर्ता को वहाँ भेजें। वह हमारा consent screen देखेगा, निर्णय लेगा, और आपके पास वापस redirect हो जाएगा।

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

उपयोगकर्ता हमारे consent screen पर पहुँचता है, sign in करता है (यदि पहले से नहीं), और स्वीकार या अस्वीकार करता है। स्वीकृति पर हम आपके redirect_uri पर short-lived ?code=… के साथ redirect करते हैं, ?error=access_denied अस्वीकार पर। आपका मूल state वापस आता है — सत्यापित करें कि यह मेल खाता है।

3.3 code को access_token के लिए exchange करें

अपने backend से, code (और PKCE verifier) को एक 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"

Response (24h TTL):

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

3.4 token का उपयोग करें

userinfo endpoint या प्रदत्त scopes के अनुमत किसी भी /v1/* route को call करें:

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

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

जैसे fields email, github_email, discord_username केवल तभी दिखाई देते हैं जब उपयोगकर्ता ने उन्हें वास्तव में verify / link कर लिया हो। उपस्थिति और अनुपस्थिति दोनों के लिए योजना बनाएं।

एक token revoke करना

जब कोई उपयोगकर्ता आपके ऐप से sign out करता है, तो token को revoke करें ताकि वह background में उनके अकाउंट को billing करता न रहे:

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

RFC 7009। हमेशा 200 लौटाता है, चाहे token मौजूद हो या नहीं (कोई oracle नहीं)।

सुरक्षा नोट्स

PKCE सार्वजनिक clients के लिए अनिवार्य है (कोई server-side client_secret नहीं)। हम केवल S256 स्वीकार करते हैं — code_challenge_method=plain अस्वीकार किया जाता है।
redirect_uri exact-match है। कोई prefix / wildcard matching नहीं। यदि आपको कई environments की आवश्यकता है, तो प्रति environment एक URI register करें।
Tokens का 24h TTL है और अभी कोई refresh tokens नहीं — expire होने पर, उपयोगकर्ता को फिर से /oauth/authorize के माध्यम से चलाएं। लंबे समय तक चलने वाले agents के लिए, startup पर prompt करें और token को secure storage में रखें।
client_secret को client-side कोड में store न करें। यदि आपका ऐप browser-only SPA या native client है, तो server के बिना register करें और PKCE पर भरोसा करें।
उपयोगकर्ता अपने dashboard → Apps tab से किसी भी समय आपके ऐप को revoke कर सकते हैं। OAuth flow को फिर से चलाकर 401 को handle करें।
Phase 1 कवरेज: OAuth bearer tokens /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/images/generations, और /oauth/userinfo. पर काम करते हैं। Audio, video, voice, और character endpoints को Phase 1 में अभी भी एक नियमित Airforce API key की आवश्यकता है।

रजिस्टर करें

ईमेल करें [email protected] या हमें यहाँ ping करें Discord ऊपर सूचीबद्ध registration विवरणों के साथ। हम आपको कुछ ही घंटों में आपकी credentials वापस भेज देंगे।

Airforce से साइन इन करें