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 da 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 comoBearer <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)
Para saber mais sobre as APIs disponíveis, visite Referência da Logto Account API e Referência da Logto Verification API.
Os recursos de visualização de conta SSO e exclusão de conta estão disponíveis atualmente 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 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 válido por 10 minutos. Veja Obter um ID de registro de verificação.
- 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:
- Os campos incluem: nome de usuário, nome, avatar, perfil (outros atributos padrão de perfil) e dados personalizados.
- Usuários finais podem editar esses campos sem verificação adicional.
- 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 que os usuários façam login novamente. A recuperação de tokens fica disponível automaticamente após habilitar a Account API.
Como acessar a Account API
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
],
};
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. 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 na solicitação de concessão do 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.
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 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, a Account API exige 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 expiração de 10 minutos (TTL). Isso pode ser usado para verificar a identidade do usuário antes de atualizar informações sensíveis. Ou seja, uma vez que o usuário verifica sua identidade com sucesso via senha, código de verificação por email ou SMS, ele tem 10 minutos para atualizar seus dados relacionados à autenticação, incluindo identificadores, credenciais, vinculação de conta social 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 será assim:
{
"verificationRecordId": "...",
"expiresAt": "..."
}
Verificar enviando um código de verificação para o email ou telefone do usuário
Para usar este método, você precisa configurar o conector de email ou conector de SMS, e garantir que o template UserPermissionValidation esteja configurado.
Usando 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 será assim:
{
"verificationRecordId": "...",
"expiresAt": "..."
}
Ao receber o código de verificação, você pode usá-lo para atualizar o status de verificação do registro.
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 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, inclua o ID de registro de verificação no cabeçalho da requisição com o campo logto-verification-id.
Atualizar a senha do usuário
Para atualizar a senha do usuário, utilize 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":"..."}'
Assim como as senhas criadas durante o cadastro, as 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
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, chame 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 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json' \
--data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'
Assim como os emails coletados durante o cadastro, qualquer email vinculado pela Account API deve passar pela verificação da 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, utilize 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
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.
Vincular uma nova conexão social
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 evitar 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 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json' \
--data-raw '{"newIdentifierVerificationRecordId":"..."}'
Remover uma conexão social
Para remover uma conexão social, utilize 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 passkey WebAuthn
Lembre-se de habilitar MFA e WebAuthn primeiro.
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
As 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 aplicativo front-end chama a Account API de um domínio diferente das páginas de autenticação do Logto, é necessário configurar as Related Origins para permitir operações de passkey entre domínios.
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 serauth.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"]}'
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.comehttps://auth.example.comcontam como um rótulo (example.com)https://shopping.com,https://shopping.co.ukehttps://shopping.co.jptambém contam como um rótulo (shopping)https://example.comehttps://another.comcontam 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: Solicitar 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, utilize 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.
Este passo 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 de registro de verificação retornado pelo servidor no passo 1.
Passo 5: Vincular a passkey
Por fim, vincule 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 '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; consulte a seção Obter um ID de registro de verificação para mais detalhes.type: o tipo do fator MFA, atualmente apenasWebAuthné suportado.newIdentifierVerificationRecordId: o ID de registro de verificação retornado pelo servidor no passo 1.
Gerenciar passkeys WebAuthn existentes
Para gerenciar passkeys WebAuthn existentes, utilize 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,WebAuthnpara 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 'logto-verification-id: <verification_record_id>' \
-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>' \
-H 'logto-verification-id: <verification_record_id>'
Vincular um novo TOTP
Lembre-se de habilitar MFA e TOTP primeiro.
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 para o 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 aplicativo autenticador (como Google Authenticator, Microsoft Authenticator ou Authy).
O formato URI para o QR code deve ser:
otpauth://totp/[Emissor]:[Conta]?secret=[Segredo]&issuer=[Emissor]
Exemplo:
otpauth://totp/SeuApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=SeuApp
Passo 3: Vincular o fator TOTP
Após o usuário adicionar o segredo ao 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. Consulte a seção Obter um ID de registro de verificação para mais detalhes.type: deve serTotp.secret: o segredo TOTP gerado no passo 1.
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.
Gerenciar códigos de backup
Lembre-se de habilitar MFA e códigos de backup primeiro.
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 para o 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
Exiba os códigos em formato claro e fácil de copiar e considere 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 '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. Consulte a seção Obter um ID de registro de verificação para mais detalhes.type: deve serBackupCode.codes: o array de códigos de backup gerados no passo anterior.
- 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 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 os códigos de backup existentes e seu status de uso, utilize 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,nullse ainda não foi usado.