個人存取權杖 (Personal access token)
個人存取權杖(PAT, Personal access tokens)為使用者提供一種安全方式,以授予存取權杖 (Access token),而無需使用其憑證或互動式登入。這對於 CI / CD、自動化腳本或需要以程式方式存取資源的應用程式特別有用。
管理個人存取權杖
使用 Console
你可以在 Console > 使用者管理 (User management) 的使用者詳情頁面管理個人存取權杖。在「驗證 (Authentication)」卡片中,你可以查看個人存取權杖清單並建立新的權杖。
使用 Management API
設定好 Management API 後,你可以使用 API 端點 來建立、列出及刪除個人存取權杖。
使用 PAT 取得存取權杖
建立 PAT 後,你可以透過權杖交換端點,將其用於為你的應用程式取得存取權杖。
請求
應用程式會以 HTTP POST 方法,向租戶的 權杖端點 (token endpoint) 發起權杖交換請求 (token exchange request),並使用特殊的 grant type。HTTP 請求主體採用 application/x-www-form-urlencoded
格式,包含以下參數:
client_id
:必填。應用程式的 client ID。grant_type
:必填。此參數值必須為urn:ietf:params:oauth:grant-type:token-exchange
,表示正在執行權杖交換。resource
:選填。資源標示符 (resource indicator),與其他權杖請求相同。scope
:選填。請求的權限範圍 (scopes),與其他權杖請求相同。subject_token
:必填。使用者的 PAT。subject_token_type
:必填。subject_token
參數所提供安全權杖的型別。此參數值必須為urn:logto:token-type:personal_access_token
。
回應
若權杖交換請求成功,租戶的權杖端點會回傳一個代表使用者身分的存取權杖。回應內容以 application/json
格式,包含以下參數:
access_token
:必填。使用者的存取權杖,與authorization_code
或refresh_token
等其他權杖請求相同。issued_token_type
:必填。發行權杖的型別。此參數值必須為urn:ietf:params:oauth:token-type:access_token
。token_type
:必填。權杖型別。此參數值必須為Bearer
。expires_in
:必填。存取權杖的有效秒數。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"
}
相關資源
什麼是個人存取權杖?什麼時候該使用個人存取權杖?
個人存取權杖、機器對機器驗證 (Machine-to-Machine authentication) 與 API 金鑰的定義及實際應用場景