Configurações de conta pela Account API

O que é a Logto Account API

A Logto Account API é um conjunto abrangente de APIs que oferece aos usuários finais acesso direto via API sem a necessidade de passar pela Management API. Aqui estão os destaques:

Acesso direto: A Account API permite que os usuários finais acessem e gerenciem diretamente seus próprios perfis de conta sem precisar do repasse pela Management API.
Gerenciamento de perfil de usuário e identidades: Os usuários podem gerenciar totalmente seus perfis e configurações de segurança, incluindo a capacidade de atualizar informações de identidade como email, telefone e senha, além de gerenciar conexões sociais. Suporte a MFA e SSO em breve.
Controle de acesso global: Os administradores têm controle total e global sobre as configurações de acesso e podem personalizar cada campo.
Autorização (Authorization) sem atrito: A autorização nunca foi tão fácil! Basta usar client.getAccessToken() para obter um token opaco de acesso para OP (Logto) e anexá-lo ao cabeçalho Authorization como Bearer <access_token>.

Com a Logto Account API, você pode construir um sistema personalizado de gerenciamento de contas, como uma página de perfil totalmente integrada ao Logto.

Alguns casos de uso frequentes estão listados abaixo:

Recuperar perfil do usuário
Atualizar perfil do usuário
Atualizar senha do usuário
Atualizar identidades do usuário, incluindo email, telefone e conexões sociais
Gerenciar fatores de MFA (verificações)
Gerenciar sessões do usuário
Gerenciar aplicativos autorizados do usuário (grants)

Para saber mais sobre as APIs disponíveis, visite Referência da Logto Account API e Referência da Logto Verification API.

nota:

Os recursos de visualização de conta SSO e exclusão de conta estão atualmente disponíveis através das Management APIs do Logto. Veja Configurações de conta pela Management API para detalhes de implementação.

Como habilitar a Account API

Navegue até Console > Login & conta > Central da conta.

A Account API vem desativada por padrão, então seus controles de acesso estão bloqueados. Ative Habilitar Account API para ligá-la.

Uma vez habilitada, configure a janela de Autenticação recente (de 1 a 120 minutos; 10 minutos por padrão) e permissões por campo para identificadores, dados de perfil e acesso a tokens de terceiros. Cada campo suporta Off, ReadOnly ou Edit; o padrão é Off.

Campos de segurança:
- Campos incluem: email principal, telefone principal, identidades sociais, senha, passkeys, MFA e tokens de acesso pessoal.
- Operações sensíveis exigem autenticação recente do usuário a partir de um aplicativo de primeira parte — um token de acesso cujo acr satisfaça urn:logto:acr:1fa dentro da janela de autenticação recente configurada (veja Autenticação step-up OIDC).
- Para usar passkeys WebAuthn para MFA, adicione os domínios do seu app front-end em WebAuthn Related Origins para que a central da conta e a experiência de login possam compartilhar passkeys. Veja Vincular uma nova passkey WebAuthn.
Campos de perfil:
- Campos incluem: nome de usuário, nome, avatar, profile (outros atributos padrão de perfil) e custom data.
- Usuários finais podem editar esses campos sem verificação adicional, exceto username, que também exige autenticação recente do usuário.
Cofre de segredos:
- Para conectores sociais e corporativos OIDC ou OAuth, o cofre de segredos do Logto armazena com segurança tokens de acesso e atualização de terceiros após a autenticação. Os apps podem então chamar APIs externas, como sincronizar eventos do Google Agenda, sem pedir ao usuário para fazer login novamente. A recuperação de tokens fica disponível automaticamente após habilitar a Account API.
Gerenciamento de sessões:
- Quando habilitado, os usuários podem visualizar e gerenciar suas sessões ativas, incluindo informações do dispositivo e último login. Usuários também podem revogar sessões para sair de dispositivos específicos.
- Essa mesma permissão de campo Sessions também controla as APIs de aplicativos autorizados do usuário (grants) (visualizar e revogar grants).
- O acesso ao gerenciamento de sessões e grants exige a mesma autenticação recente do usuário que os campos de segurança.

Como acessar a Account API

nota:

Para garantir que o token de acesso tenha as permissões apropriadas, certifique-se de configurar corretamente os escopos correspondentes em sua configuração do Logto.

Por exemplo, para a API POST /api/my-account/primary-email, você precisa configurar o escopo email; para a API POST /api/my-account/primary-phone, você precisa configurar o escopo phone.

import { type LogtoConfig, UserScope } from '@logto/js';

const config: LogtoConfig = {
  // ...outras opções
  // Adicione os escopos adequados para seus casos de uso.
  scopes: [
    UserScope.Email, // Para as APIs `{POST,DELETE} /api/my-account/primary-email`
    UserScope.Phone, // Para as APIs `{POST,DELETE} /api/my-account/primary-phone`
    UserScope.CustomData, // Para gerenciar dados personalizados
    UserScope.Address, // Para gerenciar endereço
    UserScope.Identities, // Para APIs relacionadas a identidade e MFA
    UserScope.Profile, // Para gerenciar perfil do usuário
    UserScope.Sessions, // Para gerenciar sessões do usuário e grants de apps
  ],
};

Buscar um token de acesso

Após configurar o SDK em seu aplicativo, você pode usar o método client.getAccessToken() para buscar um token de acesso. Esse token é um token opaco que pode ser usado para acessar a Account API.

Se você não estiver usando o SDK oficial, deve definir o resource como vazio na solicitação de concessão de token de acesso para /oidc/token.

Acessar a Account API usando o token de acesso

Você deve incluir o token de acesso no campo Authorization dos cabeçalhos HTTP no formato Bearer (Bearer YOUR_TOKEN) ao interagir com a Account API.

Veja um exemplo para obter as informações da conta do usuário:

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

Gerenciar informações básicas da conta

Recuperar informações da conta do usuário

Para obter os dados do usuário, você pode usar o endpoint GET /api/my-account.

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

O corpo da resposta será assim:

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

Os campos da resposta podem variar dependendo das configurações da central da conta.

Atualizar informações básicas da conta

As informações básicas da conta incluem nome de usuário, nome, avatar, dados personalizados e outras informações de perfil.

Para atualizar username, name, avatar e customData você pode usar o endpoint PATCH /api/my-account.

curl -X PATCH https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"username":"...","name":"...","avatar":"..."}'

Para atualizar outras informações de perfil, incluindo familyName, givenName, middleName, nickname, profile (URL da página de perfil), website, gender, birthdate, zoneinfo, locale e address, você pode usar o endpoint PATCH /api/my-account/profile.

curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"familyName":"...","givenName":"..."}'

Gerenciar identificadores e outras informações sensíveis

Por motivos de segurança, operações sensíveis da Account API exigem autenticação recente do usuário a partir de um aplicativo de primeira parte: o token de acesso deve conter acr satisfazendo urn:logto:acr:1fa e um auth_time dentro da janela de Autenticação recente do seu tenant (600 segundos / 10 minutos por padrão, configurável de 60 a 7.200 segundos).

Quando o token de acesso não possui urn:logto:acr:1fa ou está fora da janela, a Account API retorna 401 Unauthorized com um cabeçalho RFC 9470 WWW-Authenticate (error="insufficient_user_authentication", acr_values="urn:logto:acr:1fa", max_age="<window>"). Inicie uma solicitação de autenticação step-up OIDC com esses parâmetros e tente novamente com o novo token de acesso emitido.

nota:

Vincular um novo endereço de email, número de telefone, identidade social ou passkey WebAuthn também exige comprovação de posse desse novo identificador ou fator via Verification API e passar newIdentifierVerificationRecordId no corpo da requisição, conforme mostrado em cada seção abaixo.

Atualizar a senha do usuário

Para atualizar a senha do usuário, você pode usar o endpoint POST /api/my-account/password.

curl -X POST https://[tenant-id].logto.app/api/my-account/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

dica:

Assim como senhas criadas durante o cadastro, senhas definidas pela Account API devem estar em conformidade com a política de senha que você configurou em Console > Segurança > Política de senha. O Logto retorna resultados detalhados de validação e mensagens de erro se a senha não atender à política.

Atualizar ou vincular novo email

nota:

Para usar este método, você precisa configurar o conector de email e garantir que o template BindNewIdentifier esteja configurado.

Para atualizar ou vincular um novo email, primeiro você deve comprovar a posse do email.

Chame o endpoint POST /api/verifications/verification-code para solicitar um código de verificação.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

Você encontrará um verificationId na resposta e receberá um código de verificação no email, use-o para verificar o email.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}'

Após verificar o código, você pode chamar PATCH /api/my-account/primary-email para atualizar o email do usuário, definindo o verificationId no corpo da requisição como newIdentifierVerificationRecordId.

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

dica:

Assim como emails coletados durante o cadastro, qualquer email vinculado pela Account API deve passar pela verificação de blocklist que você configurou em Console > Segurança > Blocklist. O Logto rejeitará a solicitação e retornará um erro detalhado se o email violar a política.

Remover o email do usuário

Para remover o email do usuário, você pode usar o endpoint DELETE /api/my-account/primary-email.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>'

Gerenciar telefone

nota:

Para usar este método, você precisa configurar o conector de SMS e garantir que o template BindNewIdentifier esteja configurado.

Semelhante à atualização de email, você pode usar o endpoint PATCH /api/my-account/primary-phone para atualizar ou vincular um novo telefone. E usar o endpoint DELETE /api/my-account/primary-phone para remover o telefone do usuário.

Para vincular uma nova conexão social, primeiro solicite uma URL de autorização com POST /api/verifications/social.

curl -X POST https://[tenant-id].logto.app/api/verifications/social \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}'

connectorId: O ID do conector social.
redirectUri: O URI de redirecionamento após o usuário autorizar o aplicativo; você deve hospedar uma página web neste URL e capturar o callback.
state: O estado a ser retornado após o usuário autorizar o aplicativo; é uma string aleatória usada para prevenir ataques CSRF.

Na resposta, você encontrará um verificationRecordId, guarde-o para uso posterior.

Após o usuário autorizar o aplicativo, você receberá um callback no redirectUri com o parâmetro state. Então, use o endpoint POST /api/verifications/social/verify para verificar a conexão social.

curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorData":"...","verificationRecordId":"..."}'

O connectorData são os dados retornados pelo conector social após o usuário autorizar o aplicativo; você precisa analisar e obter os parâmetros de consulta do redirectUri em sua página de callback e empacotá-los como JSON no campo connectorData.

Por fim, use o endpoint POST /api/my-account/identities para vincular a conexão social.

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'

Para remover uma conexão social, use o endpoint DELETE /api/my-account/identities.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \
  -H 'authorization: Bearer <access_token>'

Vincular uma nova passkey WebAuthn

nota:

Lembre-se de habilitar MFA e WebAuthn primeiro.

nota:

Para usar este método, você precisa habilitar o campo mfa nas configurações da central da conta.

Passo 1: Adicione a origem do seu app front-end às origens relacionadas

Passkeys WebAuthn são vinculadas a um hostname específico chamado Relying Party ID (RP ID). Apenas aplicativos hospedados na origem do RP ID podem registrar ou autenticar com essas passkeys.

Como seu app front-end chama a Account API de um domínio diferente das páginas de autenticação do Logto, você precisa configurar Related Origins para permitir operações de passkey entre origens.

Como o Logto determina o RP ID:

Configuração padrão: Se você usa apenas o domínio padrão do Logto https://[tenant-id].logto.app, o RP ID é [tenant-id].logto.app
Domínio personalizado: Se você configurou um domínio personalizado como https://auth.example.com, o RP ID passa a ser auth.example.com

Configurar Related Origins:

Use o endpoint PATCH /api/account-center para adicionar a origem do seu app front-end. Por exemplo, se a central da conta do seu app roda em https://account.example.com:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'

nota:

O WebAuthn suporta até 5 rótulos eTLD+1 únicos para Related Origins. O eTLD+1 (domínio de nível superior efetivo mais um rótulo) é a parte registrável do domínio. Por exemplo:

https://example.com, https://app.example.com e https://auth.example.com contam como um rótulo (example.com)
https://shopping.com, https://shopping.co.uk e https://shopping.co.jp também contam como um rótulo (shopping)
https://example.com e https://another.com contam como dois rótulos

Se precisar suportar mais de 5 domínios diferentes como Related Origins, consulte a documentação Related Origin Requests para detalhes.

Passo 2: Solicite novas opções de registro

Use o endpoint POST /api/verifications/web-authn/registration para solicitar o registro de uma nova passkey. O Logto permite que cada conta de usuário registre múltiplas passkeys.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Você receberá uma resposta como:

{
  "registrationOptions": "...",
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Passo 3: Registrar a passkey no navegador local

Usando @simplewebauthn/browser como exemplo, você pode usar a função startRegistration para registrar a passkey no navegador local.

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // Os dados retornados pelo servidor no passo 1
});
// Salve a resposta para uso posterior

Passo 4: Verificar o registro da passkey

Use o endpoint POST /api/verifications/web-authn/registration/verify para verificar o registro da passkey.

Esta etapa verifica a assinatura criptográfica gerada pelo autenticador para garantir que a passkey foi criada legitimamente e não foi adulterada durante a transmissão.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"payload":"...","verificationRecordId":"..."}'

payload: A resposta do navegador local no passo 2.
verificationRecordId: O ID do registro de verificação retornado pelo servidor no passo 1.

Passo 5: Vincular a passkey

Por fim, você pode vincular a passkey à conta do usuário usando o endpoint POST /api/my-account/mfa-verifications.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'

type: o tipo do fator MFA, atualmente apenas WebAuthn é suportado.
newIdentifierVerificationRecordId: o ID do registro de verificação retornado pelo servidor no passo 1.

Gerenciar passkeys WebAuthn existentes

Para gerenciar passkeys WebAuthn existentes, use o endpoint GET /api/my-account/mfa-verifications para obter as passkeys atuais e outros fatores de verificação MFA.

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>'

O corpo da resposta será assim:

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]

id: o ID da verificação.
type: o tipo da verificação, WebAuthn para passkey WebAuthn.
name: o nome da passkey, campo opcional.
agent: o user agent da passkey.

Atualize o nome da passkey usando o endpoint PATCH /api/my-account/mfa-verifications/{verificationId}/name:

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"name":"..."}'

Exclua a passkey usando o endpoint DELETE /api/my-account/mfa-verifications/{verificationId}:

curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
  -H 'authorization: Bearer <access_token>'

Vincular um novo TOTP

nota:

Lembre-se de habilitar MFA e TOTP primeiro.

nota:

Para usar este método, você precisa habilitar o campo mfa nas configurações da central da conta.

Passo 1: Gerar um segredo TOTP

Use o endpoint POST /api/my-account/mfa-verifications/totp-secret/generate para gerar um segredo TOTP.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

O corpo da resposta será assim:

{
  "secret": "..."
}

Passo 2: Exibir o segredo TOTP ao usuário

Use o segredo para gerar um QR code ou exibi-lo diretamente ao usuário. O usuário deve adicioná-lo ao seu app autenticador (como Google Authenticator, Microsoft Authenticator ou Authy).

O formato URI para o QR code deve ser:

otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

Exemplo:

otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

Passo 3: Vincular o fator TOTP

Após o usuário adicionar o segredo ao app autenticador, ele deve verificá-lo e vinculá-lo à sua conta. Use o endpoint POST /api/my-account/mfa-verifications para vincular o fator TOTP.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'

type: deve ser Totp.
secret: o segredo TOTP gerado no passo 1.

nota:

Um usuário só pode ter um fator TOTP por vez. Se o usuário já tiver um fator TOTP, tentar adicionar outro resultará em erro 422.

Substituir um TOTP existente

Se o usuário já tiver um fator TOTP configurado, você pode substituí-lo por um novo usando o endpoint PUT /api/my-account/mfa-verifications/totp. Esta é uma operação idempotente que remove o TOTP existente e vincula um novo.

nota:

Para usar este método, você precisa habilitar o campo mfa nas configurações da central da conta.

Passo 1: Gerar um novo segredo TOTP

Use o endpoint POST /api/my-account/mfa-verifications/totp-secret/generate para gerar um novo segredo TOTP e exibi-lo ao usuário conforme descrito em Vincular um novo TOTP.

Passo 2: Substituir o fator TOTP

curl -X PUT https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"secret":"...","code":"..."}'

secret: o novo segredo TOTP gerado no passo 1.
code: o código TOTP gerado a partir do novo segredo para confirmar a vinculação.

Gerenciar códigos de backup

nota:

Lembre-se de habilitar MFA e códigos de backup primeiro.

nota:

Para usar este método, você precisa habilitar o campo mfa nas configurações da central da conta.

Passo 1: Gerar novos códigos de backup

Use o endpoint POST /api/my-account/mfa-verifications/backup-codes/generate para gerar um novo conjunto de 10 códigos de backup.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

O corpo da resposta será assim:

{
  "codes": ["...", "...", "..."]
}

Passo 2: Exibir códigos de backup ao usuário

Antes de vincular os códigos de backup à conta do usuário, você deve exibi-los ao usuário e instruí-lo a:

Baixar ou anotar esses códigos imediatamente
Armazená-los em local seguro
Entender que cada código só pode ser usado uma vez
Saber que esses códigos são o último recurso caso perca acesso aos métodos MFA principais

Você deve exibir os códigos de forma clara, fácil de copiar e considerar fornecer uma opção de download (por exemplo, como arquivo de texto ou PDF).

Passo 3: Vincular códigos de backup à conta do usuário

Use o endpoint POST /api/my-account/mfa-verifications para vincular os códigos de backup à conta do usuário.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'

type: deve ser BackupCode.
codes: o array de códigos de backup gerados na etapa anterior.

nota:

Um usuário só pode ter um conjunto de códigos de backup por vez. Se todos os códigos forem usados, o usuário precisa gerar e vincular novos códigos.
Códigos de backup não podem ser o único fator MFA. O usuário deve ter pelo menos um outro fator MFA (como WebAuthn ou TOTP) habilitado.
Cada código de backup só pode ser usado uma vez.

Visualizar códigos de backup existentes

Para visualizar códigos de backup existentes e seu status de uso, use o endpoint GET /api/my-account/mfa-verifications/backup-codes:

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \
  -H 'authorization: Bearer <access_token>'

O corpo da resposta será assim:

{
  "codes": [
    {
      "code": "...",
      "usedAt": null
    },
    {
      "code": "...",
      "usedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

code: o código de backup.
usedAt: o timestamp de quando o código foi usado, null se ainda não foi usado.

Gerenciar configurações de verificação em 2 etapas

nota:

Para usar esses métodos, você precisa habilitar o campo mfa nas configurações da central da conta.

Usuários finais podem ativar ou desativar a verificação em 2 etapas para sua conta. Um caso comum é quando o usuário configurou fatores MFA (como passkeys), mas deseja usá-los apenas para login, não como uma etapa adicional de verificação — desabilitar a verificação em 2 etapas permite pular o prompt de MFA durante o login, mantendo os fatores MFA ativos. Isso é controlado pela configuração skipMfaOnSignIn por usuário.

Obter configurações atuais de MFA

Use o endpoint GET /api/my-account/mfa-settings para recuperar as configurações atuais de verificação em 2 etapas do usuário.

curl https://[tenant-id].logto.app/api/my-account/mfa-settings \
  -H 'authorization: Bearer <access_token>'

O corpo da resposta será assim:

{
  "skipMfaOnSignIn": false
}

Atualizar configurações de MFA

Para ativar ou desativar a verificação em 2 etapas, use o endpoint PATCH /api/my-account/mfa-settings.

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-settings \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"skipMfaOnSignIn":true}'

skipMfaOnSignIn: defina como true para desativar a verificação em 2 etapas para o usuário, ou false para ativá-la.

nota:

Esta configuração só tem efeito quando a política de MFA está definida como Opcional. Se o MFA estiver como Obrigatório ou Adaptativo, a configuração skipMfaOnSignIn será ignorada e o MFA será exigido.

Gerenciar sessões do usuário

Listar sessões ativas

Para listar as sessões ativas do usuário, use o endpoint GET /api/my-account/sessions.

nota:

O escopo UserScope.Sessions é necessário para acessar este endpoint.
O campo Sessions nas configurações da central da conta deve estar como ReadOnly ou Edit.

curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Revogar sessão por ID da sessão

Para revogar uma sessão específica, use o endpoint DELETE /api/my-account/sessions/{sessionId}.

nota:

O escopo UserScope.Sessions é necessário para acessar este endpoint.
O campo Sessions nas configurações da central da conta deve estar como Edit.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Parâmetros de consulta opcionais:

revokeGrantsTarget: Opcionalmente, especifique o alvo dos grants a serem revogados junto com a sessão. Valores possíveis:
- all: Revoga todos os grants associados à sessão.
- firstParty: Revoga apenas grants de apps de primeira parte associados à sessão. (Recomendado para a maioria dos casos, pois revoga o acesso do seu próprio app mantendo grants de apps de terceiros, proporcionando melhor experiência ao usuário.)
- não especificado: O comportamento padrão revoga grants que não possuem o escopo offline_access, o que normalmente significa revogar grants sem refresh token para a sessão.

Gerenciar aplicativos autorizados do usuário (grants)

Use as APIs de aplicativos autorizados do usuário (grants) quando os usuários precisarem revisar e revogar apps autorizados na página de configurações da conta.

nota:

As APIs de grants de apps compartilham o mesmo modelo de permissão das APIs de sessão.
O escopo UserScope.Sessions é necessário.
O campo Sessions nas configurações da central da conta deve estar habilitado:
- ReadOnly ou Edit para listar grants.
- Edit para revogar grants.

Listar grants de apps ativos

Para listar os grants de apps ativos do usuário atual, use o endpoint GET /api/my-account/grants.

curl https://[tenant-id].logto.app/api/my-account/grants \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Parâmetro de consulta opcional:

appType=firstParty: Retorna apenas grants de apps de primeira parte.
appType=thirdParty: Retorna apenas grants de apps de terceiros.
Omitir appType: Retorna todos os grants ativos.

curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Revogar grant de app por ID do grant

Para revogar um grant de app específico, use o endpoint DELETE /api/my-account/grants/{grantId}.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Quando um grant é revogado, tokens de acesso opacos e tokens de atualização emitidos anteriormente para esse grant são invalidados.

O que é a Logto Account API​

Como habilitar a Account API​

Como acessar a Account API​

Buscar um token de acesso​

Acessar a Account API usando o token de acesso​

Gerenciar informações básicas da conta​

Recuperar informações da conta do usuário​

Atualizar informações básicas da conta​

Gerenciar identificadores e outras informações sensíveis​

Atualizar a senha do usuário​

Atualizar ou vincular novo email​

Remover o email do usuário​

Gerenciar telefone​

Vincular uma nova conexão social​

Remover uma conexão social​

Vincular uma nova passkey WebAuthn​

Gerenciar passkeys WebAuthn existentes​

Vincular um novo TOTP​

Substituir um TOTP existente​

Gerenciar códigos de backup​

Gerenciar configurações de verificação em 2 etapas​

Gerenciar sessões do usuário​

Gerenciar aplicativos autorizados do usuário (grants)​

O que é a Logto Account API

Como habilitar a Account API

Como acessar a Account API

Buscar um token de acesso

Acessar a Account API usando o token de acesso

Gerenciar informações básicas da conta

Recuperar informações da conta do usuário

Atualizar informações básicas da conta

Gerenciar identificadores e outras informações sensíveis

Atualizar a senha do usuário

Atualizar ou vincular novo email

Remover o email do usuário

Gerenciar telefone

Vincular uma nova conexão social

Remover uma conexão social

Vincular uma nova passkey WebAuthn

Gerenciar passkeys WebAuthn existentes

Vincular um novo TOTP

Substituir um TOTP existente

Gerenciar códigos de backup

Gerenciar configurações de verificação em 2 etapas

Gerenciar sessões do usuário

Gerenciar aplicativos autorizados do usuário (grants)