Saltar al contenido principal

Configuración de cuenta mediante Account API

¿Qué es la Logto Account API?​

La Logto Account API es un conjunto completo de APIs que brinda a los usuarios finales acceso directo a la API sin necesidad de pasar por la Management API. Aquí tienes los aspectos destacados:

  • Acceso directo: La Account API permite a los usuarios finales acceder y gestionar directamente sus propios perfiles de cuenta sin requerir el uso intermedio de la Management API.
  • Gestión de perfil de usuario e identidades: Los usuarios pueden gestionar completamente sus perfiles y configuraciones de seguridad, incluyendo la capacidad de actualizar información de identidad como correo electrónico, teléfono y contraseña, así como gestionar conexiones sociales. El soporte para MFA y SSO llegará pronto.
  • Control de acceso global: Los administradores tienen control total y global sobre la configuración de acceso y pueden personalizar cada campo.
  • Autorización sin fricciones: ¡La autorización es más fácil que nunca! Simplemente usa client.getAccessToken() para obtener un token de acceso opaco para OP (Logto), y adjúntalo al encabezado Authorization como Bearer <access_token>.
nota:

Para asegurar que el token de acceso tenga los permisos apropiados, asegúrate de haber configurado correctamente los alcances correspondientes en tu configuración de Logto.

Por ejemplo, para la API POST /api/my-account/primary-email, necesitas configurar el alcance email; para la API POST /api/my-account/primary-phone, necesitas configurar el alcance phone.

import { type LogtoConfig, UserScope } from '@logto/js';

const config: LogtoConfig = {
  // ...otras opciones
  // Añade los alcances apropiados que se ajusten a tus casos de uso.
  scopes: [
    UserScope.Email, // Para las APIs `{POST,DELETE} /api/my-account/primary-email`
    UserScope.Phone, // Para las APIs `{POST,DELETE} /api/my-account/primary-phone`
    UserScope.CustomData, // Para gestionar datos personalizados
    UserScope.Address, // Para gestionar dirección
    UserScope.Identities, // Para APIs relacionadas con identidad y MFA
    UserScope.Profile, // Para gestionar el perfil de usuario
  ],
};

Con la Logto Account API, puedes construir un sistema personalizado de gestión de cuentas como una página de perfil totalmente integrada con Logto.

Algunos casos de uso frecuentes se listan a continuación:

  • Recuperar el perfil de usuario
  • Actualizar el perfil de usuario
  • Actualizar la contraseña del usuario
  • Actualizar las identidades del usuario incluyendo correo electrónico, teléfono y conexiones sociales
  • Gestionar factores de MFA (verificaciones)

Para saber más sobre las APIs disponibles, visita Referencia de Logto Account API y Referencia de Logto Verification API.

nota:

Próximamente estarán disponibles Account APIs dedicadas para las siguientes configuraciones: MFA, SSO, datos personalizados (usuario) y eliminación de cuenta. Mientras tanto, puedes implementar estas funciones usando las Management APIs de Logto. Consulta Configuración de cuenta mediante Management API para más detalles.

Cómo habilitar la Account API​

Por defecto, la Account API está deshabilitada. Para habilitarla, necesitas usar la Management API para actualizar la configuración global.

El endpoint /api/account-center puede usarse para recuperar y actualizar la configuración del centro de cuentas. Puedes usarlo para habilitar o deshabilitar la Account API y personalizar los campos.

Ejemplo de solicitud:

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

El campo enabled se usa para habilitar o deshabilitar la Account API, y el campo fields se usa para personalizar los campos, el valor puede ser Off, Edit, ReadOnly. El valor por defecto es Off. La lista de campos:

  • name: El campo de nombre.
  • avatar: El campo de avatar.
  • profile: El campo de perfil, incluyendo sus subcampos.
  • username: El campo de nombre de usuario.
  • email: El campo de correo electrónico.
  • phone: El campo de teléfono.
  • password: El campo de contraseña, al obtenerlo, devolverá true si el usuario ha establecido una contraseña, de lo contrario false.
  • social: Conexiones sociales.
  • mfa: Factores de MFA.

Aprende más sobre los detalles de la API en la Referencia de Logto Management API.

Cómo acceder a la Account API​

Obtener un token de acceso​

Después de configurar el SDK en tu aplicación, puedes usar el método client.getAccessToken() para obtener un token de acceso. Este token es un token opaco que puede usarse para acceder a la Account API.

Si no estás usando el SDK oficial, debes establecer el resource vacío para la solicitud de concesión de token de acceso a /oidc/token.

Acceder a la Account API usando el token de acceso​

Debes incluir el token de acceso en el campo Authorization de los encabezados HTTP con el formato Bearer (Bearer YOUR_TOKEN) al interactuar con la Account API.

Aquí tienes un ejemplo para obtener la información de la cuenta de usuario:

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

Gestionar información básica de la cuenta​

Recuperar información de la cuenta de usuario​

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

El cuerpo de la respuesta sería así:

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

Los campos de la respuesta pueden variar dependiendo de la configuración del centro de cuentas.

Actualizar información básica de la cuenta​

La información básica de la cuenta incluye el nombre de usuario, nombre, avatar y perfil.

Para actualizar el nombre de usuario, nombre y avatar, puedes usar el 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 actualizar el perfil, puedes usar el 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":"..."}'

Gestionar identificadores y otra información sensible​

Por razones de seguridad, la Account API requiere una capa adicional de autorización para operaciones que involucren identificadores y otra información sensible.

Obtener un ID de registro de verificación​

Primero, necesitas obtener un ID de registro de verificación. Esto puede usarse para verificar la identidad del usuario al actualizar identificadores.

Para obtener un ID de registro de verificación, puedes verificar la contraseña del usuario o enviar un código de verificación al correo electrónico o teléfono del usuario.

Para saber más sobre las verificaciones, consulta Verificación de seguridad mediante Account API.

Verificar la contraseña del usuario​

curl -X POST https://[tenant-id].logto.app/api/verifications/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

El cuerpo de la respuesta sería así:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Verificar enviando un código de verificación al correo electrónico o teléfono del usuario​

nota:

Para usar este método, necesitas configurar el conector de correo electrónico o conector SMS, y asegurarte de que la plantilla UserPermissionValidation esté configurada.

Tomando el correo electrónico como ejemplo, solicita un nuevo código de verificación y obtén el ID de registro de verificación:

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

El cuerpo de la respuesta sería así:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Al recibir el código de verificación, puedes usarlo para actualizar el estado de verificación del registro de verificación.

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

Después de verificar el código, ahora puedes usar el ID de registro de verificación para actualizar el identificador del usuario.

Enviar solicitud con ID de registro de verificación​

Al enviar una solicitud para actualizar el identificador del usuario, necesitas incluir el ID de registro de verificación en el encabezado de la solicitud con el campo logto-verification-id.

nota:

Para usar este método, necesitas configurar el conector de correo electrónico, y asegurarte de que la plantilla BindNewIdentifier esté configurada.

Para actualizar o vincular un nuevo correo electrónico, primero debes demostrar la propiedad del correo.

Llama al endpoint POST /api/verifications/verification-code para solicitar un código de verificación.

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

Encontrarás un verificationId en la respuesta, y recibirás un código de verificación en el correo electrónico, úsalo para verificar el correo.

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

Después de verificar el código, ahora puedes actualizar el correo electrónico del usuario, establece el verificationId en el cuerpo de la solicitud 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":"..."}'

Eliminar el correo electrónico del usuario​

Para eliminar el correo electrónico del usuario, puedes usar el 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>'

Gestionar teléfono​

nota:

Para usar este método, necesitas configurar el conector SMS, y asegurarte de que la plantilla BindNewIdentifier esté configurada.

De manera similar a la actualización de correo electrónico, puedes usar el endpoint PATCH /api/my-account/primary-phone para actualizar o vincular un nuevo teléfono. Y usar el endpoint DELETE /api/my-account/primary-phone para eliminar el teléfono del usuario.

Para vincular una nueva conexión social, primero debes solicitar una URL de autorización:

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: El ID del conector social.
  • redirectUri: La URI de redirección después de que el usuario autorice la aplicación, debes alojar una página web en esta URL y capturar el callback.
  • state: El estado que se devolverá después de que el usuario autorice la aplicación, es una cadena aleatoria que se usa para prevenir ataques CSRF.

En la respuesta, encontrarás un verificationRecordId, guárdalo para su uso posterior.

Después de que el usuario autorice la aplicación, recibirás un callback en el redirectUri con el parámetro state. Luego puedes usar el endpoint POST /api/verifications/social/verify para verificar la conexión 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":"..."}'

El connectorData son los datos devueltos por el conector social después de que el usuario autoriza la aplicación, necesitas analizar y obtener los parámetros de consulta del redirectUri en tu página de callback, y envolverlos como un JSON como valor del campo connectorData.

Finalmente, puedes usar el endpoint POST /api/my-account/identities para vincular la conexión 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":"..."}'

Eliminar una conexión social​

Para eliminar una conexión social, puedes usar el 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:

Recuerda habilitar MFA y WebAuthn primero.

nota:

Para usar este método, necesitas habilitar el campo mfa en la configuración del centro de cuentas.

Paso 0: Añade el origen de tu app front-end a los orígenes relacionados.

Una clave de acceso en el navegador está vinculada a un hostname específico (RP ID), y solo el origen del RP ID puede usarse para registrar o verificar una clave de acceso. Sin embargo, tu app front-end que envía la solicitud a la Account API no es la misma que la página de inicio de sesión de Logto, por lo que necesitas añadir el origen de tu app front-end a la lista de orígenes relacionados. Esto permitirá que tu app front-end registre y verifique una clave de acceso bajo otros RP IDs.

Por defecto, Logto establecerá el RP ID al dominio del tenant, por ejemplo, si tu dominio de tenant es https://example.logto.app, el RP ID será example.logto.app. Si usas un dominio personalizado, el RP ID será el dominio personalizado, por ejemplo, si tu dominio personalizado es https://auth.example.com, el RP ID será auth.example.com.

Ahora, añade el origen de tu app front-end a los orígenes relacionados, por ejemplo, si el origen de tu app front-end es 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 más sobre los orígenes relacionados, consulta la documentación de Related Origin Requests.

Paso 1: solicita nuevas opciones 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'

Recibirás una respuesta como:

{
  "registrationOptions": "...",
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Paso 2: registra la clave de acceso en el navegador local.

Tomando @simplewebauthn/browser como ejemplo, puedes usar la función startRegistration para registrar la clave de acceso en el navegador local.

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // Los datos devueltos por el servidor en el paso 1
});
// Guarda la respuesta para su uso posterior

Paso 3: verifica la clave de acceso.

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: La respuesta del navegador local en el paso 2.
  • verificationRecordId: El ID de registro de verificación devuelto por el servidor en el paso 1.

Paso 4: finalmente, puedes vincular la clave de acceso.

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: un ID de registro de verificación válido, otorgado al verificar el factor existente del usuario, puedes consultar la sección Obtener un ID de registro de verificación para más detalles.
  • type: el tipo de factor MFA, actualmente solo se admite WebAuthn.
  • newIdentifierVerificationRecordId: el ID de registro de verificación devuelto por el servidor en el paso 1.

Gestionar clave de acceso WebAuthn existente​

Para gestionar una clave de acceso WebAuthn existente, puedes usar el endpoint GET /api/my-account/mfa-verifications para obtener las claves actuales y otros factores de verificación MFA.

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>'

El cuerpo de la respuesta sería así:

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]
  • id: el ID de la verificación.
  • type: el tipo de la verificación, WebAuthn para clave de acceso WebAuthn.
  • name: el nombre de la clave de acceso, campo opcional.
  • agent: el user agent de la clave de acceso.

Actualizar el nombre de la clave de acceso:

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

Eliminar la clave de acceso:

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