Pular para o conteúdo principal

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. O suporte para MFA e SSO estará disponível 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 atrito: A autorização está 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 à 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 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.

nota:

APIs dedicadas para as seguintes configurações estarão disponíveis em breve: MFA, SSO, dados personalizados (usuário) e exclusão de conta. Enquanto isso, você pode implementar esses recursos usando as Management APIs do Logto. Veja Configurações de conta pela Management API para mais detalhes.

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, retornará true se o usuário tiver definido 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​

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

Para atualizar nome de usuário, nome e avatar, 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 o perfil, 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. Isso pode ser usado para verificar a identidade do usuário ao atualizar identificadores.

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.

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

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 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, agora você pode usar o ID de registro de verificação para atualizar o identificador do usuário.

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

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

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 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, agora você pode atualizar o email do usuário, definindo o verificationId no corpo da requisição como newIdentifierVerificationRecordId.

curl -X PATCH 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 você deve solicitar uma URL de autorização:

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

Remover uma conexão 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>'
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 0: Adicione a origem do seu app front-end às origens relacionadas.

Uma chave de acesso no navegador está vinculada a um hostname específico (RP ID), e somente a origem do RP ID pode ser usada para registrar ou verificar uma chave de acesso. No entanto, seu app front-end que está enviando a requisição para a Account API não é o mesmo que a página de login do Logto, então você precisa adicionar a origem do seu app front-end à lista de origens relacionadas. Isso permitirá que seu app front-end registre e verifique uma chave de acesso sob outros RP IDs.

Por padrão, o Logto definirá o RP ID como o domínio do tenant, por exemplo, se seu domínio for https://example.logto.app, o RP ID será example.logto.app. Se você estiver usando um domínio personalizado, o RP ID será o domínio personalizado, por exemplo, se seu domínio for https://auth.example.com, o RP ID será auth.example.com.

Agora, vamos adicionar a origem do seu app front-end às origens relacionadas, por exemplo, se a origem do seu app for https://account.example.com:

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

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

Passo 1: solicitar novas opções de registro.

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 2: registrar a chave de acesso no navegador local.

Usando @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 3: verificar a chave de acesso.

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 4: por fim, você pode vincular a chave de acesso.

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 apenas WebAuthn é suportado.
  • newIdentifierVerificationRecordId: o ID de registro de verificação retornado pelo servidor no passo 1.

Gerenciar chave de acesso WebAuthn existente​

Para gerenciar uma chave de acesso WebAuthn existente, 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 de acesso WebAuthn.
  • name: o nome da chave de acesso, campo opcional.
  • agent: o user agent da chave de acesso.

Atualizar o nome da chave de acesso:

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

Excluir a chave de acesso:

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