Token de acesso pessoal
Tokens de acesso pessoal (PATs) fornecem uma maneira segura para os usuários concederem token de acesso (Access token) sem usar suas credenciais e login interativo. Isso é útil para CI/CD, scripts ou aplicativos que precisam acessar recursos programaticamente.
Gerenciando tokens de acesso pessoal
Usando o Console
Você pode gerenciar tokens de acesso pessoal na página Detalhes do Usuário do Console > Gerenciamento de usuários. No cartão "Autenticação (Authentication)", você pode ver a lista de tokens de acesso pessoal e criar novos.
Usando a Management API
Após configurar a Management API, você pode usar os endpoints da API para criar, listar e excluir tokens de acesso pessoal.
Usar PATs para conceder tokens de acesso
Após criar um PAT, você pode usá-lo para conceder tokens de acesso ao seu aplicativo utilizando o endpoint de troca de token.
Tokens de acesso obtidos usando PATs funcionam identicamente aos tokens obtidos através do fluxo padrão de refresh_token
. Isso significa:
- Contexto de organização: Tokens obtidos por PAT suportam as mesmas permissões e escopos de organização que os fluxos de refresh token
- Fluxo de autorização: Você pode usar tokens de acesso trocados por PAT para permissões de organização e recursos de API em nível de organização
- Validação de token: A mesma lógica de validação se aplica – apenas o tipo de concessão inicial é diferente
Se você estiver trabalhando com organizações, os padrões de acesso e permissões são os mesmos independentemente de usar PAT ou refresh tokens.
Requisição
O aplicativo faz uma requisição de troca de token para o endpoint de token do tenant com um tipo de concessão especial usando o método HTTP POST. Os seguintes parâmetros são incluídos no corpo da requisição HTTP usando o formato application/x-www-form-urlencoded
.
client_id
: OBRIGATÓRIO. O client ID do aplicativo.grant_type
: OBRIGATÓRIO. O valor deste parâmetro deve serurn:ietf:params:oauth:grant-type:token-exchange
, indicando que uma troca de token está sendo realizada.resource
: OPCIONAL. O indicador de recurso, igual a outras requisições de token.scope
: OPCIONAL. Os escopos solicitados, igual a outras requisições de token.subject_token
: OBRIGATÓRIO. O PAT do usuário.subject_token_type
: OBRIGATÓRIO. O tipo do token de segurança fornecido no parâmetrosubject_token
. O valor deste parâmetro deve serurn:logto:token-type:personal_access_token
.
Resposta
Se a requisição de troca de token for bem-sucedida, o endpoint de token do tenant retorna um token de acesso que representa a identidade do usuário. A resposta inclui os seguintes parâmetros no corpo da resposta HTTP usando o formato application/json
.
access_token
: OBRIGATÓRIO. O token de acesso do usuário, igual a outras requisições de token comoauthorization_code
ourefresh_token
.issued_token_type
: OBRIGATÓRIO. O tipo do token emitido. O valor deste parâmetro deve serurn:ietf:params:oauth:token-type:access_token
.token_type
: OBRIGATÓRIO. O tipo do token. O valor deste parâmetro deve serBearer
.expires_in
: OBRIGATÓRIO. O tempo de vida em segundos do token de acesso.scope
: OPCIONAL. Os escopos do token de acesso.
Exemplo de troca de token
Para aplicativos web tradicionais com segredo do aplicativo:
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
Para aplicativos single-page ou nativos sem segredo do aplicativo:
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"
}
Então, se você decodificar o token de acesso com o decodificador JWT, você obterá o seguinte exemplo de payload do token de acesso:
{
"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"
}
Recursos relacionados
O que é um token de acesso pessoal? Quando devo usar tokens de acesso pessoal?
Tokens de acesso pessoal, autenticação máquina para máquina (Machine-to-Machine), definição de API Keys e seus cenários no mundo real