認證 (OAuth)

OAuth Flow

Gency 遵循 OAuth 2.0 標準，提供使用者授權應用程式權限的安全授權流程。

Authorization Code Flow

這是最建議的方式，分三個階段進行。

授權請求

將使用者重新導向至 Gency 授權頁面。

GET https://openapi.gency.ai/oauth/authorize
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={redirect_uri}
  &scope=product:read product:write
  &state={random_state}

• response_type: code（必填）
• client_id: 在 API 中心發行的 Client ID（必填）
• redirect_uri: 在 API 中心註冊的 Redirect URI（必填）
• scope: 要請求的權限（以空白分隔，省略時使用應用程式註冊的全部範圍）
• state: 防止 CSRF 用的隨機字串（建議）

Gency 收到此請求後會產生 authorize_key，並將使用者重新導向至 Gency OAuth 登入/同意頁面（https://gency.ai/oauth/authorize?authorize_key=...）。

使用者登入與同意

使用者在 Gency OAuth 頁面以電子郵件/密碼登入。登入後確認應用程式名稱、請求範圍等資訊並同意。

接收 Authorization Code 與交換權杖

使用者同意後，Gency 會將 authorization code 傳遞至已註冊的 redirect_uri。

{redirect_uri}?code={authorization_code}&state={state}

使用此代碼請求 Access Token。

POST https://openapi.gency.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={authorization_code}
&redirect_uri={redirect_uri}
&client_id={client_id}
&client_secret={client_secret}

成功時的回應：

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOi...",
  "scope": "product:read product:write"
}

Token 更新

Access Token 過期時，可使用 Refresh Token 更新。

POST https://openapi.gency.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={refresh_token}
&client_id={client_id}
&client_secret={client_secret}

Token 驗證

確認已發行權杖的有效性。

POST https://openapi.gency.ai/oauth/introspect
Content-Type: application/x-www-form-urlencoded

token={access_token}
&client_id={client_id}
&client_secret={client_secret}

Token 撤銷

使不再使用的權杖失效。

POST https://openapi.gency.ai/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token={token}
&client_id={client_id}
&client_secret={client_secret}

權杖資訊摘要

項目	值
Access Token 有效期限	1 小時 (3,600 秒)
Refresh Token 有效期限	90 天 (7,776,000 秒)
Authorization Code 有效期限	10 分鐘 (600 秒)
Token Type	Bearer
Issuer	https://openapi.gency.ai

伺服器中繼資料

OAuth2 伺服器設定資訊可在以下端點確認。

GET https://openapi.gency.ai/.well-known/oauth-authorization-server

---