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

  • Acesso direto: A Account API capacita os usuários finais a acessar e gerenciar diretamente seu próprio perfil 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: O administrador tem controle total e global sobre as configurações de acesso, podendo personalizar cada campo.
  • Autorização sem complicações: Autorizar é 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 usos frequentes estão listados abaixo:

  • Recuperar perfil de usuário
  • Atualizar perfil de usuário
  • Atualizar senha do usuário
  • Atualizar identidades do usuário, incluindo email, telefone e conexões sociais

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

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 da API /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 solicitaçã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. A lista de campos:

  • name: O campo de nome.
  • avatar: O campo de avatar.
  • profile: O campo de perfil, incluindo seus subcampos.
  • username: O campo de nome de usuário.
  • email: O campo de email.
  • phone: O campo de telefone.
  • password: O campo de senha, ao obter, retornará true se o usuário tiver definido uma senha, caso contrário, false.
  • social: Conexões sociais.

Saiba mais sobre os detalhes da API em Logto Management API Reference.

Como acessar a Account API​

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 colocar o token de acesso no campo Authorization dos cabeçalhos HTTP com o formato Bearer (Bearer YOUR_TOKEN) ao interagir com a Account API.

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 seria 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 o nome de usuário, nome, avatar e perfil.

Para atualizar o 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 razões de segurança, a Account API requer outra camada de autorização para as 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.

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.

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

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

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

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 PATCH 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 atualizar o email do usuário, definir o verificationId no corpo da solicitaçã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 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 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 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 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 PATCH /api/my-account/identities para vincular a conexão social.

curl -X PATCH 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>'