跳至主要內容

個人存取權杖 (Personal access token)

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

管理個人存取權杖​

使用 Console​

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

使用 Management API​

設定好 Management API 後，你可以透過 API 端點 建立、列出及刪除個人存取權杖。

使用 PAT 授予存取權杖​

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

權杖流程等價性:

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

若你正在與組織 (Organizations) 搭配使用，無論使用 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：選填。存取權杖的權限範圍 (Scopes)。

權杖交換範例​

對於具有 app secret 的傳統 Web 應用程式：

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%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn%3Alogto%3Atoken-type%3Apersonal_access_token

對於無 app secret 的單頁或原生應用程式：

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%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=http://my-api.com
&scope=read
&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",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read"
}

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

{
  "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 金鑰的定義及實際應用場景