跳至主要內容

個人存取權杖 (Personal access token)

個人存取權杖(PAT, Personal access tokens)為使用者提供一種安全方式,以授予存取權杖 (Access token),而無需使用其憑證或互動式登入。這對於 CI / CD、自動化腳本或需要以程式方式存取資源的應用程式特別有用。

管理個人存取權杖

使用 Console

你可以在 Console > 使用者管理 的使用者詳細頁面管理個人存取權杖。在「驗證 (Authentication)」卡片中,你可以查看個人存取權杖清單並建立新的權杖。

使用 Management API

設定好 Management API 後,你可以使用 API 端點 來建立、列出和刪除個人存取權杖。

使用 PAT 授予存取權杖

建立 PAT 後,你可以透過權杖交換端點,使用它為你的應用程式授予存取權杖。

權杖流程等價性:

使用 PAT 取得的存取權杖,與標準 refresh_token 流程取得的權杖完全相同。這表示:

如果你正在處理組織,無論使用 PAT 或重新整理權杖 (Refresh token),存取模式與權限皆相同。

請求

應用程式會以 HTTP POST 方法,向租戶的 權杖端點 (Token endpoint) 發送權杖交換請求 (Token exchange request),並使用特殊的 grant type。HTTP 請求主體採用 application/x-www-form-urlencoded 格式,包含以下參數:

  1. client_id:必填。應用程式的 client ID。
  2. grant_type:必填。此參數值必須為 urn:ietf:params:oauth:grant-type:token-exchange,表示正在執行權杖交換。
  3. resource:選填。資源標示符 (Resource indicator),與其他權杖請求相同。
  4. scope:選填。請求的權限範圍 (Scopes),與其他權杖請求相同。
  5. subject_token:必填。使用者的 PAT。
  6. subject_token_type:必填。subject_token 參數所提供安全權杖的型態。此參數值必須為 urn:logto:token-type:personal_access_token

回應

若權杖交換請求成功,租戶的權杖端點會回傳代表使用者身分的存取權杖。HTTP 回應主體採用 application/json 格式,包含以下參數:

  1. access_token:必填。使用者的存取權杖,與 authorization_coderefresh_token 等其他權杖請求相同。
  2. issued_token_type:必填。發行權杖的型態。此參數值必須為 urn:ietf:params:oauth:token-type:access_token
  3. token_type:必填。權杖型態。此參數值必須為 Bearer
  4. expires_in:必填。存取權杖的存活時間(秒)。
  5. scope:選填。存取權杖的權限範圍 (Scopes)。

權杖交換範例

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client-id:client-secret)>

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&scope=profile
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn%3Alogto%3Atoken-type%3Apersonal_access_token
HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token": "eyJhbGci...zg",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "profile"
}

存取權杖 (Access token) 負載範例:

{
"jti": "iFtbZBeh2M1cTTBuKbHk4",
"sub": "123",
"iss": "https://tenant.logto.app/oidc",
"exp": 1672531200,
"iat": 1672527600,
"scope": "profile",
"client_id": "client-id"
}

什麼是個人存取權杖 (Personal access token)?什麼時候該使用個人存取權杖?

個人存取權杖 (Personal Access Tokens)、機器對機器驗證 (Machine-to-Machine authentication) 與 API 金鑰 (API Keys) 定義及實際應用場景