Masuk dengan Airforce

Untuk siapa ini

Kamu sedang membangun aplikasi (playground, agen, klien mobile, …) dan ingin penggunamu menghubungkan akun Airforce mereka sehingga mereka bisa menjalankan chat atau pembuatan gambar melalui UI-mu tanpa membagikan API key mentah mereka kepadamu. Gunakan alur ini.

Kamu akan mendapatkan access_token opak (24h TTL) yang dibatasi pada apa yang diminta aplikasimu dan disetujui pengguna. Gunakan sebagai header Bearer terhadap endpoint /v1/* atau /oauth/userinfo.

1. Dapatkan client_id + client_secret

Phase 1 adalah pendaftaran yang dikelola admin. Hubungi kami dengan:

• Nama aplikasi (ditampilkan di layar persetujuan kepada penggunamu)
• Deskripsi satu kalimat
• URL beranda (opsional, ditampilkan di persetujuan)
• URL logo persegi (opsional)
• Satu atau lebih redirect_uri yang tepat (hanya https://, kecuali http://localhost untuk dev)
• Scope apa yang kamu butuhkan (lihat di bawah)

Kami mengirimkan kembali client_id dan satu kali client_secret. Simpan secret di sisi server — jika kamu adalah SPA murni / aplikasi native tanpa backend, kamu bisa melewatkan secret dan hanya mengandalkan PKCE.

2. Scope

Beberapa scope dipisahkan dengan spasi dalam parameter query scope : scope=profile chat images.

3. Alur

3.1 Buat pasangan PKCE

Di klienmu, sebelum mengarahkan ke /oauth/authorize, buat verifier acak dan challenge SHA-256 yang cocok.

// 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 Arahkan ke /oauth/authorize

Bangun URL authorize dan kirim pengguna ke sana. Dia akan melihat layar persetujuan kami, memutuskan, dan diarahkan kembali kepadamu.

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

Pengguna mendarat di layar persetujuan kami, masuk (jika belum), dan menyetujui atau menolak. Kami mengarahkan kembali ke redirect_uri milikmu dengan ?code=… berumur pendek saat menyetujui, ?error=access_denied saat menolak. Original state milikmu dikembalikan — pastikan cocok.

3.3 Tukar code untuk access_token

Dari backend-mu, tukar code (plus PKCE verifier) untuk 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"

Respon (24h TTL):

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

3.4 Gunakan token

Panggil endpoint userinfo atau rute /v1/* mana pun yang diizinkan scope yang diberikan:

# 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"}]}'

Respon /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"
}

Field seperti email, github_email, discord_username hanya muncul saat pengguna benar-benar memverifikasi / menautkannya. Rencanakan untuk keberadaan dan ketiadaan.

Mencabut token

Saat pengguna keluar dari aplikasimu, cabut token sehingga tidak terus menagih akunnya di latar belakang:

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

RFC 7009. Selalu mengembalikan 200 terlepas dari apakah token ada atau tidak (tanpa oracle).

Catatan keamanan

• PKCE wajib untuk klien publik (tanpa client_secret di sisi server). Kami hanya menerima S256 — code_challenge_method=plain ditolak.
• redirect_uri adalah exact-match. Tidak ada pencocokan prefix / wildcard. Jika kamu butuh beberapa environment, daftarkan satu URI per environment.
• Token memiliki TTL 24h dan belum ada refresh token — saat kedaluwarsa, jalankan pengguna kembali melalui /oauth/authorize lagi. Untuk agen jangka panjang, tanya di startup dan simpan token di penyimpanan aman.
• Jangan simpan client_secret di kode sisi klien. Jika aplikasimu adalah SPA browser-only atau klien native, daftar tanpa server dan andalkan PKCE.
• Pengguna dapat mencabut aplikasimu kapan saja dari dashboard → tab Apps. Tangani 401 dengan menjalankan ulang alur OAuth.
• Cakupan Phase 1: Token bearer OAuth bekerja pada /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/images/generations, dan /oauth/userinfo. Endpoint audio, video, voice, dan character masih memerlukan API key Airforce reguler di Phase 1.

Daftar

Email ke [email protected] atau hubungi kami di Discord dengan detail pendaftaran yang tercantum di atas. Kami akan mengirim kembali kredensialmu dalam beberapa jam.