快速開始

1. 註冊 Partner Client

請平台管理員為特定 Merchant 建立一個 Partner Client，選擇 production 或 sandbox，並設定精確的 redirect URI 與 scope allowlist。產生的 client_secret 只會在該次回應中顯示一次，請立即複製到你的後端 secret manager；平台只保存其 hash，之後無法再次顯示。

本機開發時，可選用的 seeder 會建立 sample-app，callback 為 sample-app://auth/ekyc/callback。可用 PARTNER_SAMPLE_APP_SECRET 覆寫其僅限本機使用的 secret。

2. 發起授權

你的 Application 以包含 client_id、redirect_uri、以空白分隔的 scope，以及不可預測的 state 的 authorize URI 開啟 eKYC App。

ekyc://authorize?client_id=sample-app&redirect_uri=sample-app%3A%2F%2Fauth%2Fekyc%2Fcallback&scope=profile.basic%20kyc.status&state=RANDOM_STATE

使用者裝置必須已安裝 eKYC 行動 App，且該 App 已註冊 ekyc://authorize custom scheme。使用者登入並明確同意後，App 會帶著 code 與 state 回到 allowlist 中的 callback。若 state 不相符，必須拒絕該 callback。目前的協定在使用者取消時不會送出任何 callback。

建議另加入選用的 S256 PKCE：由你的後端產生並保存 code_verifier，只把對應的 code_challenge 與 code_challenge_method=S256 加入 authorize URI。App 會保留並轉送 challenge；下方 token 交換 JSON 需再附上同一次請求的 code_verifier。PKCE 不會取代 client_secret。

在啟用同意動作之前，已登入的 eKYC App 會以相同的 client_id、redirect_uri 與 scope 呼叫 POST /api/partner-auth/preview。Preview 會顯示可信任的 Application、Merchant、Organization、環境、membership 狀態，以及最新的後端 Eligibility；它不會建立 membership，也不會授予授權。

3. 交換 code

從你的 Application 後端呼叫 POST /api/partner-auth/token，送出 JSON：

curl -X POST https://identity.example.com/api/partner-auth/token \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "sample-app",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "sample-app://auth/ekyc/callback"
  }'

{
  "access_token": "PARTNER_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "profile.basic kyc.status"
}

4. 讀取使用者 profile

curl https://identity.example.com/api/partner-auth/me \
  -H "Accept: application/json" \
  -H "Authorization: Bearer PARTNER_ACCESS_TOKEN"

請以回傳的 partner-specific sub 作為穩定的外部身份 key。不要以 Email 或 identity_profile_id 作為你產品帳號的 key。