跳至主要內容

個人存取權杖 (Personal access token)

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

管理個人存取權杖​

使用 Console​

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

使用 Management API​

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

使用 PAT 授予存取權杖​

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

權杖流程等價性:

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

  • 組織情境：PAT 取得的權杖支援與重新整理權杖 (refresh token) 流程相同的組織權限與權限範圍 (scopes)
  • 授權流程：你可以將 PAT 交換取得的存取權杖用於 組織權限 與 組織層級 API 資源
  • 權杖驗證：驗證邏輯完全一致，僅初始授權類型不同

若你正在處理組織，無論使用 PAT 或重新整理權杖，存取模式與權限皆相同。

請求​

應用程式會以 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_code 或 refresh_token 等其他權杖請求相同。
  2. issued_token_type：必填。發行權杖的類型。此參數值必須為 urn:ietf:params:oauth:token-type:access_token。
  3. token_type：必填。權杖的類型。此參數值必須為 Bearer。
  4. expires_in：必填。存取權杖的有效秒數。
  5. scope：選填。存取權杖的權限範圍。

權杖交換範例​

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

存取權杖範例 payload：

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

什麼是個人存取權杖？什麼時候該使用個人存取權杖？

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