跳至主要內容

個人存取權杖 (Personal access token)

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

管理個人存取權杖​

使用 Console​

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

使用 Management API​

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

使用 PAT 取得存取權杖​

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

權杖流程等價性:

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

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

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

請求​

先決條件:

在使用權杖交換 (token exchange) 授權類型前，你需要為你的應用程式啟用此功能：

  1. 前往 主控台 > 應用程式 並選擇你的應用程式。
  2. 在應用程式設定中，找到「權杖交換 (Token exchange)」區段。
  3. 啟用「允許權杖交換 (Allow token exchange)」開關。

出於安全考量，權杖交換預設為停用狀態。如果你未啟用，將會收到「此應用程式不允許權杖交換 (token exchange is not allowed for this application)」的錯誤訊息。

應用程式會以 HTTP POST 方法，使用特殊的 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。

回應​

若權杖交換請求成功，租戶的權杖端點會回傳代表使用者身分的存取權杖。回應主體以 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：選填。存取權杖的權限範圍 (Scopes)。

權杖交換範例​

對於傳統網頁應用程式或具有 app secret 的機器對機器應用程式，請將憑證以 HTTP Basic 認證方式放在 Authorization 標頭：

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

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn:logto:token-type:personal_access_token

對於單頁應用程式（SPA）或無 app secret 的原生應用程式，請將 client_id 放在請求主體：

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded

client_id=your-app-id
&grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn:logto:token-type:personal_access_token

成功回應範例：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGci...zg",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read"
}

若你使用 JWT 解碼器 解碼存取權杖，會得到如下範例 payload：

{
  "jti": "VovNyqJ5_tuYac89eTbpF",
  "sub": "rkxl1ops7gs1",
  "iat": 1756908403,
  "exp": 1756912003,
  "scope": "read",
  "client_id": "your-app-id",
  "iss": "https://tenant-id.logto.app/oidc",
  "aud": "http://my-api.com"
}

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

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