Airforceでサインイン

対象者

あなたはアプリ（プレイグラウンド、エージェント、モバイルクライアント、…）を構築していて、ユーザーが生のAPIキーをあなたに渡すことなく、あなたのUI経由でチャットや画像生成を実行できるよう、自分のAirforceアカウントを接続できるようにしたい。このフローを使ってください。

不透明な access_token を取得します（24h TTL）、アプリが要求しユーザーが承認したものに限定されます。 /v1/* エンドポイントまたは /oauth/userinfo.

1. client_id + client_secret を取得

段階 1 は管理者管理の登録です。以下を添えてご連絡ください：

• アプリ名（ユーザーへの同意画面に表示されます）
• 一文の説明
• ホームページURL（任意、同意画面に表示）
• 正方形ロゴURL（任意）
• 1つ以上の正確な redirect_uri（https://のみ、開発用のhttp://localhostを除く）
• 必要なスコープ（下記参照）

こちらからお返しするのは client_id および一度限りの client_secret. secretはサーバー側で保管してください — バックエンドのない純粋なSPA / ネイティブアプリの場合、secretをスキップしてPKCEのみに依存できます。

2. スコープ

複数のスコープはスペース区切りで scope クエリパラメータに指定します： scope=profile chat images.

3. フロー

3.1 PKCE ペアを生成

/oauth/authorize にリダイレクトする前に、クライアントでランダムな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 にリダイレクト

認可URLを構築してユーザーをそこに送ります。ユーザーは同意画面を見て、決定し、あなたのところに戻されます。

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

ユーザーは同意画面に来て、サインイン（未サインインの場合）し、承認または拒否します。私たちはあなたの redirect_uri に、短命の ?code=… を承認時に付けて、 ?error=access_denied を拒否時に付けてリダイレクトします。元の state は返されます — 一致するか確認してください。

3.3 code を access_token と交換

バックエンドから code（とPKCE verifier）をアクセストークンと交換します。

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"

レスポンス（24h TTL）：

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

3.4 トークンを使う

userinfoエンドポイント、または付与されたスコープが許可する /v1/* ルートを呼び出します：

# 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 レスポンス

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

次のようなフィールド email, github_email, discord_username は、ユーザーが実際に検証 / 連携したときにのみ表示されます。存在と不在の両方を想定してください。

トークンの失効

ユーザーがアプリからサインアウトしたら、バックグラウンドでアカウントに課金され続けないようにトークンを失効させます：

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

RFC 7009。トークンが存在したかどうかに関わらず常に 200 を返します（オラクルなし）。

セキュリティに関する注意

• PKCE はパブリッククライアントでは必須です （サーバー側 client_secret なし）。S256 のみ受け付けます — code_challenge_method=plain は拒否されます。
• redirect_uri は完全一致です。 プレフィックス / ワイルドカードのマッチングはありません。複数の環境が必要なら、環境ごとに1つのURIを登録してください。
• トークンは 24h TTL を持ち、リフレッシュトークンはまだありません — 期限切れ時はユーザーを再度 /oauth/authorize に通してください。長時間動くエージェントには、起動時にプロンプトを出し、トークンを安全なストレージに保管してください。
• client_secret をクライアントサイドコードに保存しないでください。 アプリがブラウザ専用SPAやネイティブクライアントの場合、サーバーなしで登録しPKCEに依存してください。
• ユーザーはダッシュボード → Appsタブからいつでもあなたのアプリを失効させられます。401はOAuthフローを再実行して処理してください。
• 段階 1 のカバレッジ： OAuth bearer トークンは /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/images/generations, と /oauth/userinfo. で動作します。Audio、video、voice、characterエンドポイントは段階 1 では引き続き通常のAirforce APIキーが必要です。

登録する

メールは [email protected] または Discord までご連絡ください、上記の登録詳細とともに。数時間以内に認証情報をお送りします。