Skip to main content

Personal access token

Personal access tokens (PATs) provide a secure way for users to grant access tokens without using their credentials and interactive sign-in. This is useful for CI/CD, scripts, or applications that need to access resources programmatically.

Managing personal access tokens​

Using Console​

You can manage personal access tokens in the User Details page of the Console. In the card "Authentication", you can see the list of personal access tokens and create new ones.

Using Management API​

After setting up the Management API, you can use the API endpoints to create, list, and delete personal access tokens.

Use PATs to grant access tokens​

After creating a PAT, you can use it to grant access tokens to your application by using the token exchange endpoint.

Request​

The application makes a token exchange request to the tenant's token endpoint with a special grant type using the HTTP POST method. The following parameters are included in the HTTP request entity-body using the application/x-www-form-urlencoded format.

  1. client_id: REQUIRED. The client ID of the application.
  2. grant_type: REQUIRED. The value of this parameter must be urn:ietf:params:oauth:grant-type:token-exchange indicates that a token exchange is being performed.
  3. resource: OPTIONAL. The resource indicator, the same as other token requests.
  4. scope: OPTIONAL. The requested scopes, the same as other token requests.
  5. subject_token: REQUIRED. The user's PAT.
  6. subject_token_type: REQUIRED. The type of the security token provided in the subject_token parameter. The value of this parameter must be urn:logto:token-type:personal_access_token.

Response​

If the token exchange request is successful, the tenant's token endpoint returns an access token that represents the identity of the user. The response includes the following parameters in the HTTP response entity-body using the application/json format.

  1. access_token: REQUIRED. The access token of the user, which is the same as other token requests like authorization_code or refresh_token.
  2. issued_token_type: REQUIRED. The type of the issued token. The value of this parameter must be urn:ietf:params:oauth:token-type:access_token.
  3. token_type: REQUIRED. The type of the token. The value of this parameter must be Bearer.
  4. expires_in: REQUIRED. The lifetime in seconds of the access token.
  5. scope: OPTIONAL. The scopes of the access token.

Example token exchange​

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

The example access token payload:

{
  "jti": "iFtbZBeh2M1cTTBuKbHk4",
  "sub": "123",
  "iss": "https://tenant.logto.app/oidc",
  "exp": 1672531200,
  "iat": 1672527600,
  "scope": "profile",
  "client_id": "client-id"
}