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 seu próprio perfil 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 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 fluida: Autorizar 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 como Bearer <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 usos 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

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 Logto Management APIs. 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.

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

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á semelhante a:

{
  "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, que 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 será semelhante a:

{
  "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 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á semelhante a:

{
  "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 agora 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 anexar o id de registro de verificação ao 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, você pode agora 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 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>'