跳到主要内容

个人访问令牌 (Personal access token)

个人访问令牌 (PATs) 为用户提供了一种安全的方式来授予访问令牌 (Access token)，而无需使用他们的凭据和交互式登录。这对于 CI/CD、脚本或需要以编程方式访问资源的应用程序非常有用。

管理个人访问令牌​

使用控制台​

你可以在 控制台 > 用户管理 的用户详情页中管理个人访问令牌。在“认证 (Authentication)”卡片中，你可以看到个人访问令牌列表并创建新的令牌。

使用 Management API​

在设置好 Management API 后，你可以使用 API 端点 来创建、列出和删除个人访问令牌。

使用 PAT 授予访问令牌 (Access tokens)​

创建 PAT 后，你可以通过使用令牌交换端点，将其用于为你的应用程序授予访问令牌 (Access tokens)。

令牌流程等价性:

使用 PAT 获取的访问令牌 (Access tokens) 与通过标准 refresh_token 流程获取的令牌完全相同。这意味着：

  • 组织 (Organization) 上下文：通过 PAT 获取的令牌支持与 refresh token 流程相同的组织权限和权限 (Scopes)
  • 授权 (Authorization) 流程：你可以将 PAT 交换得到的访问令牌 (Access tokens) 用于组织权限和组织级 API 资源
  • 令牌验证：验证逻辑相同——只有初始授权类型不同

如果你在使用组织 (Organizations)，无论使用 PAT 还是 refresh token，访问模式和权限都是一样的。

请求​

应用程序使用 HTTP POST 方法，向租户的 token endpoint 发送令牌交换请求，并使用特殊的授权类型。以下参数以 application/x-www-form-urlencoded 格式包含在 HTTP 请求实体主体中。

  1. client_id：必填。应用程序的 client ID。
  2. grant_type：必填。该参数的值必须为 urn:ietf:params:oauth:grant-type:token-exchange，表示正在执行令牌交换。
  3. resource：可选。资源指示器，与其他令牌请求相同。
  4. scope：可选。请求的权限 (Scopes)，与其他令牌请求相同。
  5. subject_token：必填。用户的 PAT。
  6. subject_token_type：必填。subject_token 参数中提供的安全令牌类型。该参数的值必须为 urn:logto:token-type:personal_access_token。

响应​

如果令牌交换请求成功，租户的 token endpoint 会返回一个代表用户身份的访问令牌 (Access token)。响应以 application/json 格式在 HTTP 响应实体主体中包含以下参数。

  1. access_token：必填。用户的访问令牌 (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：必填。访问令牌 (Access token) 的有效期（秒）。
  5. scope：可选。访问令牌 (Access token) 的权限 (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 解码器 解码访问令牌 (Access token)，你会得到如下示例访问令牌 (Access token) 负载：

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

什么是个人访问令牌 (Personal access token)？什么时候应该使用个人访问令牌 (Personal access token)？

个人访问令牌 (Personal Access Tokens)、机器对机器 (Machine-to-Machine) 认证 (Authentication) 和 API Keys 的定义及其实际场景