跳到主要内容

个人访问令牌 (Personal access token)

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

管理个人访问令牌 (Personal access tokens)​

使用控制台​

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

使用 Management API​

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

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

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

令牌流等价性:

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

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

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

请求​

前置条件:

在使用令牌交换授权（token exchange grant）之前，你需要为你的应用程序启用它：

  1. 前往 控制台 > 应用程序 并选择你的应用程序。
  2. 在应用程序设置中，找到“令牌交换”部分。
  3. 启用“允许令牌交换”开关。

出于安全原因，令牌交换默认是禁用的。如果你没有启用它，你将会收到“此应用程序不允许令牌交换”的错误。

应用程序使用 HTTP POST 方法，向租户的 token 端点 发起令牌交换请求，并使用特殊的授权类型。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。

响应​

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

  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)。

令牌交换示例​

对于传统 Web 应用程序或带有 app secret 的机器对机器应用程序，在 Authorization 头中使用 HTTP Basic 认证包含凭据：

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 解码器 解码访问令牌 (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 tokens)？

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