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 exigir o 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 perfeita: A autorização ficou mais fácil do que nunca! 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>.

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 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
  ],
};

Com a Logto Account API, você pode construir um sistema personalizado de gerenciamento de conta, 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.

nota:

As funcionalidades 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

Por padrão, a Account API está desabilitada. Para habilitá-la, você precisa usar a Management API para atualizar as configurações globais.

O endpoint /api/account-center pode ser usado para recuperar e atualizar as configurações do centro de contas. Você pode usá-lo para habilitar ou desabilitar a Account API e personalizar os campos.

Exemplo de requisição:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token for Logto Management API>' \
  -H 'content-type: application/json' \
  --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'

O campo enabled é usado para habilitar ou desabilitar a Account API, e o campo fields é usado para personalizar os campos, o valor pode ser Off, Edit, ReadOnly. O valor padrão é Off. Lista de campos:

name: O campo nome.
avatar: O campo avatar.
profile: O campo perfil, incluindo seus subcampos.
username: O campo nome de usuário.
email: O campo email.
phone: O campo telefone.
password: O campo senha; ao obter, retorna true se o usuário definiu uma senha, caso contrário false.
social: Conexões sociais.
mfa: Fatores de MFA.

Saiba mais sobre os detalhes da API em Referência da Logto Management API.

Como acessar a Account API

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 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.

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

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 verification record id

Primeiro, você precisa obter um verification record ID 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. Isso significa que, 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 verification record ID, 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

nota:

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 verification record ID:

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, agora você pode usar o verification record ID para atualizar o identificador do usuário.

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

Enviar requisição com verification record id

Ao enviar uma requisição para atualizar o identificador do usuário, você precisa incluir o verification record ID 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, 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":"..."}'

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

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 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, 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 empacotá-los como JSON no campo connectorData.

Por fim, você pode usar 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":"..."}'

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 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 app front-end às origens relacionadas

As chaves 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 chaves.

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 cruzada.

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 se torna auth.example.com

Configurar Related Origins:

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

Para saber mais sobre Related Origins, consulte a documentação Related Origin Requests.

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. O Logto permite que cada conta de usuário registre múltiplas chaves.

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 no navegador local

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

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

Este passo verifica a assinatura criptográfica gerada pelo autenticador para garantir que a chave 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 verification record ID retornado pelo servidor no passo 1.

Passo 5: Vincular a chave

Por fim, você pode vincular a chave à 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 verification record ID válido, concedido ao verificar o fator existente do usuário; consulte a seção Obter um verification record ID para mais detalhes.
type: o tipo do fator MFA, atualmente apenas WebAuthn é suportado.
newIdentifierVerificationRecordId: o verification record ID retornado pelo servidor no passo 1.

Gerenciar chaves WebAuthn existentes

Para gerenciar chaves WebAuthn existentes, você pode usar o endpoint GET /api/my-account/mfa-verifications para obter as chaves 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 chave WebAuthn.
name: o nome da chave, campo opcional.
agent: o user agent da chave.

Atualize o nome da chave 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 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 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/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

Exemplo:

otpauth://totp/YourApp:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

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 verification record ID válido, concedido ao verificar o fator existente do usuário. Consulte a seção Obter um verification record ID para mais detalhes.
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.

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

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

verification_record_id: um verification record ID válido, concedido ao verificar o fator existente do usuário. Consulte a seção Obter um verification record ID para mais detalhes.
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 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, 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.

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​

Obter um verification record id​

Verificar a senha do usuário​

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

Enviar requisição com verification record id​

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

Gerenciar chaves WebAuthn existentes​

Vincular um novo TOTP​

Gerenciar códigos de backup​

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

Obter um verification record id

Verificar a senha do usuário

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

Enviar requisição com verification record id

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 WebAuthn

Gerenciar chaves WebAuthn existentes

Vincular um novo TOTP

Gerenciar códigos de backup