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 à API sem precisar passar pela Management API. Aqui estão os destaques:

Acesso direto: A Account API capacita os usuários finais a acessar e gerenciar diretamente seus próprios perfis de conta sem exigir o uso da Management API.
Gerenciamento de perfil de usuário e identidades: Os usuários podem gerenciar completamente seus perfis e configurações de segurança, incluindo a capacidade de atualizar informações de identidade como email, telefone e senha, bem como gerenciar conexões sociais. Suporte para 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 sem complicações: A autorização é mais fácil do que nunca! Basta usar client.getAccessToken() para obter um token de acesso opaco para OP (Logto) e anexá-lo ao cabeçalho de Autorização como Bearer <access_token>.

Com a Logto Account API, você pode construir um sistema de gerenciamento de contas personalizado, 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 de usuário
Gerenciar aplicativos autorizados do usuário (concessões)

Para saber mais sobre as APIs disponíveis, visite Logto Account API Reference e Logto Verification API Reference.

nota:

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

Como habilitar a Account API

Navegue até Console > Sign-in & account > Account center.

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

Uma vez ativada, configure 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:
- Os campos incluem: email principal, telefone principal, identidades sociais, senha e MFA.
- Antes que os usuários finais editem esses campos, eles devem verificar sua identidade via senha, email ou SMS para obter um ID de registro de verificação de 10 minutos. Veja Obter um ID de registro de verificação.
- Para usar chaves de acesso WebAuthn para MFA, adicione os domínios do seu aplicativo front-end a WebAuthn Related Origins para que o centro de contas e a experiência de login possam compartilhar chaves de acesso. Veja Vincular uma nova chave de acesso WebAuthn.
Campos de perfil:
- Os campos incluem: nome de usuário, nome, avatar, perfil (outros atributos de perfil padrão) e dados personalizados.
- Os usuários finais podem editar esses campos sem verificação adicional.
Cofre de segredos:
- Para conectores sociais e empresariais OIDC ou OAuth, o Logto cofre de segredos armazena com segurança tokens de acesso e atualização de terceiros após a autenticação. Os aplicativos podem então chamar APIs externas, como sincronizar eventos do Google Calendar, sem solicitar que os usuários façam login novamente. A recuperação de tokens se torna disponível automaticamente uma vez que a Account API é habilitada.
Gerenciamento de sessões:
- Quando habilitado, os usuários podem visualizar e gerenciar suas sessões ativas, incluindo informações do dispositivo e última hora de login. Os 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 (visualizar e revogar concessões).
- Antes que os usuários finais acessem o gerenciamento de sessões, eles devem verificar sua identidade via senha, email ou SMS para obter um ID de registro de verificação de 10 minutos. Veja Obter um ID de registro de verificação.

Como acessar a Account API

nota:

Para garantir que o token de acesso tenha as permissões apropriadas, certifique-se de ter configurado 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 escopos adequados que se encaixem em 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 de usuário
    UserScope.Sessions, // Para gerenciar sessões de usuário e concessões de aplicativos
  ],
};

Obter um token de acesso

Após configurar o SDK em seu aplicativo, você pode usar o método client.getAccessToken() para obter um token de acesso. Este 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 para a 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 com o formato Bearer (Bearer YOUR_TOKEN) ao interagir com a Account API.

Aqui está 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 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 seria assim:

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

Os campos de resposta podem variar dependendo das configurações do centro de contas.

Atualizar informações básicas da conta

As informações básicas da conta incluem o 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 razões de segurança, a Account API requer uma camada adicional de autorização para operações que envolvem identificadores e outras informações sensíveis.

Obter um ID de registro de verificação

Primeiro, você precisa obter um ID de registro de verificação com uma expiração de 10 minutos (TTL). Isso pode ser usado para verificar a identidade do usuário antes de atualizar informações sensíveis. Isso significa que, uma vez que um usuário verifica com sucesso sua identidade via senha, código de verificação por email ou código de verificação por SMS, ele tem 10 minutos para atualizar seus dados relacionados à autenticação, incluindo identificadores, credenciais, vinculação de contas sociais e MFA.

Para obter um ID de registro de verificação, você pode verificar a senha do usuário ou enviar um código de verificação para o email ou telefone do usuário.

Verificar a senha do usuário

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

O corpo da resposta seria assim:

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

Verificar enviando um código de verificação para o email ou telefone do usuário

nota:

Para usar este método, você precisa configurar o conector de email ou conector de SMS, e certificar-se de que o template UserPermissionValidation está configurado.

Pegue o email como exemplo, solicite um novo código de verificação e obtenha o ID de registro 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":"..."}}'

O corpo da resposta seria assim:

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

Ao receber o código de verificação, você pode usá-lo para atualizar o status de verificação do registro de verificação.

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":"123456"}'

Após verificar o código, você pode agora usar o ID de registro de verificação para atualizar o identificador do usuário.

Para saber mais sobre verificações, consulte Verificação de segurança pela Account API.

Enviar solicitação com ID de registro de verificação

Ao enviar uma solicitação para atualizar o identificador do usuário, você precisa incluir o ID de registro de verificação no cabeçalho da solicitação com o campo logto-verification-id.

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 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

dica:

Assim como senhas criadas durante o cadastro, senhas definidas através da Account API devem cumprir com a política de senhas que você configurou em Console > Security > Password policy. O Logto retorna resultados detalhados de validação e mensagens de erro se a senha não cumprir a política.

Atualizar ou vincular novo email

nota:

Para usar este método, você precisa configurar o conector de email, e certificar-se de que o template BindNewIdentifier está configurado.

Para atualizar ou vincular um novo email, você deve primeiro provar a propriedade 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 agora chamar PATCH /api/my-account/primary-email para atualizar o email do usuário, defina o verificationId no corpo da solicitação como newIdentifierVerificationRecordId.

Dois IDs de registro de verificação diferentes:

Esta solicitação requer dois IDs de registro de verificação separados:

logto-verification-id (cabeçalho): Prova a identidade do usuário antes de fazer alterações sensíveis. Obtenha isso verificando a senha do usuário ou enviando um código de verificação para o email ou telefone existente do usuário.
newIdentifierVerificationRecordId (corpo): Prova a propriedade do novo endereço de email. Este é o verificationRecordId retornado da chamada POST /api/verifications/verification-code acima.

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  # Verifica a identidade do usuário (da senha ou verificação de email/telefone existente)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # O "newIdentifierVerificationRecordId" prova a propriedade do novo email (do fluxo de código de verificação acima)
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

dica:

Assim como emails coletados durante o cadastro, qualquer email vinculado através da Account API deve passar pela verificação da lista de bloqueio que você configurou em Console > Security > 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>' \
  -H 'logto-verification-id: <verification_record_id>'

Gerenciar telefone

nota:

Para usar este método, você precisa configurar o conector de SMS, e certificar-se de que o template BindNewIdentifier está 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 use o endpoint DELETE /api/my-account/primary-phone para remover o telefone do usuário.

Para vincular uma nova conexão social, primeiro você deve solicitar 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 da 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 você pode usar 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 envolvê-los como um JSON como o valor do campo connectorData.

Finalmente, você pode usar o endpoint POST /api/my-account/identities para vincular a conexão social.

Dois IDs de registro de verificação diferentes:

Esta solicitação requer dois IDs de registro de verificação separados:

logto-verification-id (cabeçalho): Prova a identidade do usuário antes de fazer alterações sensíveis. Obtenha isso verificando a senha do usuário ou enviando um código de verificação para o email ou telefone existente do usuário.
newIdentifierVerificationRecordId (corpo): Identifica a identidade social a ser vinculada. Este é o verificationRecordId retornado da chamada POST /api/verifications/social acima.

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  # Verifica a identidade do usuário (da senha ou verificação de email/telefone existente)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # O "newIdentifierVerificationRecordId" identifica a conexão social a ser vinculada (do fluxo de verificação social acima)
  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'

Para remover uma conexão social, você pode usar 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>' \
  -H 'logto-verification-id: <verification_record_id>'

Vincular uma nova chave de acesso 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 do centro de contas.

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

As chaves de acesso WebAuthn estã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 chaves de acesso.

Como seu aplicativo 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 chave de acesso entre origens.

Como o Logto determina o RP ID:

Configuração padrão: Se você usar 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 se torna auth.example.com

Configurar Origens Relacionadas:

Use o endpoint PATCH /api/account-center para adicionar a origem do seu aplicativo front-end. Por exemplo, se o centro de contas do seu aplicativo estiver 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 Origens Relacionadas. O eTLD+1 (domínio de nível superior efetivo mais um rótulo) é a parte do domínio registrável. 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 você precisar suportar mais de 5 domínios diferentes como Origens Relacionadas, consulte a documentação Related Origin Requests para detalhes.

Passo 2: Solicitar novas opções de registro

Use o endpoint POST /api/verifications/web-authn/registration para solicitar o registro de uma nova chave de acesso. O Logto permite que cada conta de usuário registre várias chaves de acesso.

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 chave de acesso no navegador local

Pegue @simplewebauthn/browser como exemplo, você pode usar a função startRegistration para registrar a chave de acesso 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 chave de acesso

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

Este passo verifica a assinatura criptográfica gerada pelo autenticador para garantir que a chave de acesso 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 de registro de verificação retornado pelo servidor no passo 1.

Passo 5: Vincular a chave de acesso

Finalmente, você pode vincular a chave de acesso à 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 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'

verification_record_id: um ID de registro de verificação válido, concedido ao verificar o fator existente do usuário, você pode consultar a seção Obter um ID de registro de verificação para mais detalhes.
type: o tipo do fator de MFA, atualmente apenas WebAuthn é suportado.
newIdentifierVerificationRecordId: o ID de registro de verificação retornado pelo servidor no passo 1.

Gerenciar chaves de acesso WebAuthn existentes

Para gerenciar chaves de acesso WebAuthn existentes, você pode usar o endpoint GET /api/my-account/mfa-verifications para obter chaves de acesso atuais e outros fatores de verificação de MFA.

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

O corpo da resposta seria assim:

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

id: o ID da verificação.
type: o tipo da verificação, WebAuthn para chave de acesso WebAuthn.
name: o nome da chave de acesso, campo opcional.
agent: o agente do usuário da chave de acesso.

Atualize o nome da chave de acesso 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 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"name":"..."}'

Exclua a chave de acesso 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>' \
  -H 'logto-verification-id: <verification_record_id>'

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 do centro de contas.

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 seria assim:

{
  "secret": "..."
}

Passo 2: Exibir o segredo TOTP para o usuário

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

O formato URI para o código QR 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 ter adicionado o segredo ao seu aplicativo autenticador, ele precisa 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 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'

verification_record_id: um ID de registro de verificação válido, concedido ao verificar o fator existente do usuário. Você pode consultar a seção Obter um ID de registro de verificação para mais detalhes.
type: deve ser Totp.
secret: o segredo TOTP gerado no passo 1.

nota:

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

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 do centro de contas.

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 seria assim:

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

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

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

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

Você deve exibir os códigos em um formato claro e fácil de copiar e considerar fornecer uma opção de download (por exemplo, como um 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 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'

verification_record_id: um ID de registro de verificação válido, concedido ao verificar o fator existente do usuário. Você pode consultar a seção Obter um ID de registro de verificação para mais detalhes.
type: deve ser BackupCode.
codes: o array de códigos de backup gerados na etapa anterior.

nota:

Um usuário pode ter apenas um conjunto de códigos de backup por vez. Se todos os códigos tiverem sido usados, o usuário precisará gerar e vincular novos códigos.
Códigos de backup não podem ser o único fator de MFA. O usuário deve ter pelo menos um outro fator de 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 seria assim:

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

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

Gerenciar sessões de usuário

Listar sessões ativas

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

nota:

O escopo UserScope.Sessions é necessário para acessar este endpoint.
O campo Sessions nas configurações do centro de contas deve estar definido como ReadOnly ou Edit.

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

Revogar sessão por ID de 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 do centro de contas deve estar definido como Edit.

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

Parâmetros de consulta opcionais:

revokeGrantsTarget: Opcionalmente, especifique o alvo das concessões a serem revogadas junto com a sessão. Valores possíveis:
- all: Revogar todas as concessões associadas à sessão.
- firstParty: Revogar apenas concessões de aplicativos de primeira parte associadas à sessão. (Recomendado para a maioria dos casos de uso, pois revoga o acesso ao seu próprio aplicativo enquanto mantém as concessões de aplicativos de terceiros intactas, proporcionando uma melhor experiência ao usuário.)
- não especificado: O comportamento padrão revoga concessões que não têm o escopo offline_access, o que geralmente significa revogar concessões não relacionadas a tokens de atualização para a sessão.

Gerenciar aplicativos autorizados do usuário (concessões)

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

nota:

As APIs de concessão de aplicativos compartilham o mesmo modelo de permissão que as APIs de sessão.
O escopo UserScope.Sessions é necessário.
O campo Sessions nas configurações do centro de contas deve estar habilitado:
- ReadOnly ou Edit para listar concessões.
- Edit para revogar concessões.

Listar concessões de aplicativos ativas

Para listar concessões de aplicativos ativas 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 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Parâmetro de consulta opcional:

appType=firstParty: Retornar apenas concessões de aplicativos de primeira parte.
appType=thirdParty: Retornar apenas concessões de aplicativos de terceiros.
Omitir appType: Retornar todas as concessões ativas.

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

Revogar concessão de aplicativo por ID de concessão

Para revogar uma concessão de aplicativo específica, 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 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Quando uma concessão é revogada, tokens de acesso opacos e tokens de atualização emitidos anteriormente para essa concessão são invalidados.

O que é a Logto Account API​

Como habilitar a Account API​

Como acessar a Account API​

Obter 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​

Obter um ID de registro de verificação​

Verificar a senha do usuário​

Verificar enviando um código de verificação para o email ou telefone do usuário​

Enviar solicitação com ID de registro de verificação​

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 chave de acesso WebAuthn​

Gerenciar chaves de acesso WebAuthn existentes​

Vincular um novo TOTP​

Gerenciar códigos de backup​

Gerenciar sessões de usuário​

Gerenciar aplicativos autorizados do usuário (concessões)​

O que é a Logto Account API

Como habilitar a Account API

Como acessar a Account API

Obter 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

Obter um ID de registro de verificação

Verificar a senha do usuário

Verificar enviando um código de verificação para o email ou telefone do usuário

Enviar solicitação com ID de registro de verificação

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 chave de acesso WebAuthn

Gerenciar chaves de acesso WebAuthn existentes

Vincular um novo TOTP

Gerenciar códigos de backup

Gerenciar sessões de usuário

Gerenciar aplicativos autorizados do usuário (concessões)