Airforce로 로그인

대상

당신은 앱(플레이그라운드, 에이전트, 모바일 클라이언트, …)을 만들고 있으며, 사용자가 자신의 원본 API 키를 당신에게 공유하지 않고도 당신의 UI를 통해 채팅이나 이미지 생성을 실행할 수 있도록 Airforce 계정을 연결하기를 원합니다. 이 플로우를 사용하세요.

불투명한 access_token 을(를) 얻습니다(24h TTL), 앱이 요청하고 사용자가 승인한 범위로 제한됩니다. /v1/* 엔드포인트 또는 /oauth/userinfo.

1. client_id + client_secret 받기

Phase 1은 관리자 관리 등록입니다. 다음 정보와 함께 연락 주세요:

• 앱 이름(사용자에게 동의 화면에 표시됨)
• 한 문장 설명
• 홈페이지 URL(선택, 동의 화면에 표시)
• 정사각형 로고 URL(선택)
• 하나 이상의 정확한 redirect_uri(https://만, dev용 http://localhost 제외)
• 필요한 scope(아래 참조)

다시 보내드리는 것은 client_id 그리고 일회용 client_secret. secret은 서버 측에 저장하세요 — 백엔드 없는 순수 SPA / 네이티브 앱이라면, secret을 건너뛰고 PKCE에만 의존할 수 있습니다.

2. Scope

여러 scope는 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)를 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"

응답(24h TTL):

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

3.4 토큰 사용

userinfo 엔드포인트 또는 부여된 scope가 허용하는 모든 /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 을(를) 반환합니다(oracle 없음).

보안 참고사항

• PKCE는 공용 클라이언트에 필수입니다 (서버 측 client_secret 없음). S256만 허용합니다 — code_challenge_method=plain 은(는) 거부됩니다.
• redirect_uri는 정확 일치입니다. 접두사 / 와일드카드 매칭 없음. 여러 환경이 필요한 경우 환경마다 하나의 URI를 등록하세요.
• 토큰은 24h TTL 을 가지며 아직 refresh 토큰은 없습니다 — 만료 시 사용자를 다시 /oauth/authorize 을(를) 통과시키세요. 장기 실행 에이전트의 경우, 시작 시 프롬프트하고 토큰을 보안 저장소에 보관하세요.
• client_secret을 클라이언트 측 코드에 저장하지 마세요. 앱이 브라우저 전용 SPA 또는 네이티브 클라이언트라면, 서버 없이 등록하고 PKCE에 의존하세요.
• 사용자는 dashboard → Apps 탭에서 언제든지 앱을 취소할 수 있습니다. OAuth 플로우를 다시 실행하여 401을 처리하세요.
• Phase 1 적용 범위: OAuth bearer 토큰은 /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/images/generations, 와(과) /oauth/userinfo. 에서 동작합니다. Audio, video, voice 및 character 엔드포인트는 Phase 1에서 여전히 일반 Airforce API 키가 필요합니다.

등록하기

이메일은 [email protected] 또는 Discord 에서 위에 나열된 등록 세부 정보와 함께 연락 주세요. 몇 시간 이내에 자격 증명을 보내드립니다.