Configuración de cuenta mediante Account API

¿Qué es Logto Account API?

La Logto Account API es un conjunto completo de APIs que ofrece a los usuarios finales acceso directo a la API sin necesidad de pasar por la Management API. Aquí están 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 de la Management API.
Gestión de perfiles 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 estará disponible pronto.
Control de acceso global: Los administradores tienen control total y global sobre las configuraciones de acceso y pueden personalizar cada campo.
Autorización sin problemas: ¡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 de Autorización como Bearer <access_token>.

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

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

Recuperar perfil de usuario
Actualizar perfil de usuario
Actualizar contraseña de usuario
Actualizar identidades de usuario incluyendo correo electrónico, teléfono y conexiones sociales
Gestionar factores de MFA (verificaciones)
Gestionar sesiones de usuario
Gestionar aplicaciones autorizadas por el usuario (concesiones)

Para obtener más información sobre las APIs disponibles, visita Logto Account API Reference y Logto Verification API Reference.

nota:

Las funciones de visualización de cuentas SSO y eliminación de cuentas están actualmente disponibles a través de las Logto Management APIs. Consulta Configuración de cuenta mediante Management API para detalles de implementación.

Cómo habilitar Account API

Navega a Console > Sign-in & account > Account center.

La Account API está desactivada por defecto, por lo que sus controles de acceso están bloqueados. Activa Enable Account API para encenderla.

Una vez habilitada, configura los permisos por campo para identificadores, datos de perfil y acceso a tokens de terceros. Cada campo admite Off, ReadOnly o Edit; el valor predeterminado es Off.

Campos de seguridad:
- Los campos incluyen: correo electrónico principal, teléfono principal, identidades sociales, contraseña y MFA.
- Antes de que los usuarios finales editen estos campos, deben verificar su identidad a través de contraseña, correo electrónico o SMS para obtener un ID de registro de verificación de 10 minutos. Consulta Obtener un ID de registro de verificación.
- Para usar claves de paso WebAuthn para MFA, agrega los dominios de tus aplicaciones front-end a WebAuthn Related Origins para que el centro de cuentas y la experiencia de inicio de sesión puedan compartir claves de paso. Consulta Vincular una nueva clave de paso WebAuthn.
Campos de perfil:
- Los campos incluyen: nombre de usuario, nombre, avatar, perfil (otros atributos de perfil estándar) y datos personalizados.
- Los usuarios finales pueden editar estos sin verificación adicional.
Bóveda secreta:
- Para conectores sociales y empresariales OIDC o OAuth, Logto bóveda secreta almacena de forma segura los tokens de acceso y actualización de terceros después de la autenticación. Las aplicaciones pueden entonces llamar a APIs externas, como sincronizar eventos de Google Calendar, sin pedir a los usuarios que inicien sesión nuevamente. La recuperación de tokens se vuelve disponible automáticamente una vez que la Account API está habilitada.
Gestión de sesiones:
- Cuando está habilitada, los usuarios pueden ver y gestionar sus sesiones activas, incluyendo información del dispositivo y la última hora de inicio de sesión. Los usuarios también pueden revocar sesiones para cerrar sesión desde dispositivos específicos.
- Este mismo permiso de campo Sessions también controla las APIs de aplicaciones autorizadas por el usuario (ver y revocar concesiones).
- Antes de que los usuarios finales accedan a la gestión de sesiones, deben verificar su identidad a través de contraseña, correo electrónico o SMS para obtener un ID de registro de verificación de 10 minutos. Consulta Obtener un ID de registro de verificación.

Cómo acceder a Account API

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
  // Agrega los alcances adecuados 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 la dirección
    UserScope.Identities, // Para APIs relacionadas con identidad y MFA
    UserScope.Profile, // Para gestionar el perfil de usuario
    UserScope.Sessions, // Para gestionar sesiones de usuario y concesiones de aplicaciones
  ],
};

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 se puede usar para acceder a la Account API.

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

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

Para obtener datos de usuario, puedes usar el endpoint GET /api/my-account.

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

El cuerpo de la respuesta sería como:

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

Los campos de 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, datos personalizados y otra información de perfil.

Para actualizar username, name, avatar, y customData 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 otra información de perfil, incluyendo familyName, givenName, middleName, nickname, profile (URL de la página de perfil), website, gender, birthdate, zoneinfo, locale, y address, 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 involucran identificadores y otra información sensible.

Obtener un ID de registro de verificación

Primero, necesitas obtener un ID de registro de verificación con una expiración de 10 minutos (TTL). Esto se puede usar para verificar la identidad del usuario antes de actualizar información sensible. Esto significa que una vez que un usuario verifica exitosamente su identidad a través de contraseña, código de verificación por correo electrónico o código de verificación por SMS, tiene 10 minutos para actualizar sus datos relacionados con la autenticación, incluyendo identificadores, credenciales, vinculación de cuentas sociales y MFA.

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.

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

{
  "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 de SMS, y asegurarte de que la plantilla UserPermissionValidation esté configurada.

Toma 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 como:

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

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

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.

Actualizar la contraseña del usuario

Para actualizar la contraseña del usuario, puedes usar el 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":"..."}'

tip:

Al igual que las contraseñas creadas durante el registro, las contraseñas establecidas a través de la Account API deben cumplir con la política de contraseñas que configuraste en Console > Security > Password policy. Logto devuelve resultados de validación detallados y mensajes de error si la contraseña no cumple con la política.

Actualizar o vincular un nuevo correo electrónico

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 electrónico.

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 electrónico.

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 llamar a PATCH /api/my-account/primary-email para actualizar el correo electrónico del usuario, establece el verificationId en el cuerpo de la solicitud como newIdentifierVerificationRecordId.

Dos diferentes IDs de registro de verificación:

Esta solicitud requiere dos IDs de registro de verificación separados:

logto-verification-id (encabezado): Demuestra la identidad del usuario antes de realizar cambios sensibles. Obtén esto verificando la contraseña del usuario o enviando un código de verificación al correo electrónico o teléfono existente del usuario.
newIdentifierVerificationRecordId (cuerpo): Demuestra la propiedad de la nueva dirección de correo electrónico. Este es el verificationRecordId devuelto por la llamada POST /api/verifications/verification-code anterior.

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  # Verifica la identidad del usuario (de la contraseña o verificación de correo electrónico/teléfono existente)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # El "newIdentifierVerificationRecordId" demuestra la propiedad del nuevo correo electrónico (del flujo de código de verificación anterior)
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

tip:

Al igual que los correos electrónicos recopilados durante el registro, cualquier correo electrónico vinculado a través de la Account API debe pasar la verificación de lista de bloqueo que configuraste en Console > Security > Blocklist. Logto rechazará la solicitud y devolverá un error detallado si el correo electrónico viola la política.

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 de SMS, y asegurarte de que la plantilla BindNewIdentifier esté configurada.

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 usa 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 con 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: 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 la devolución de llamada.
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 uso posterior.

Después de que el usuario autorice la aplicación, recibirás una devolución de llamada 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 es el dato devuelto por el conector social después de que el usuario autorice la aplicación, necesitas analizar y obtener los parámetros de consulta del redirectUri en tu página de devolución de llamada, y envolverlos como un JSON como el valor del campo connectorData.

Finalmente, puedes usar el endpoint POST /api/my-account/identities para vincular la conexión social.

Dos diferentes IDs de registro de verificación:

Esta solicitud requiere dos IDs de registro de verificación separados:

logto-verification-id (encabezado): Demuestra la identidad del usuario antes de realizar cambios sensibles. Obtén esto verificando la contraseña del usuario o enviando un código de verificación al correo electrónico o teléfono existente del usuario.
newIdentifierVerificationRecordId (cuerpo): Identifica la identidad social que se está vinculando. Este es el verificationRecordId devuelto por la llamada POST /api/verifications/social anterior.

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  # Verifica la identidad del usuario (de la contraseña o verificación de correo electrónico/teléfono existente)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # El "newIdentifierVerificationRecordId" identifica la conexión social a vincular (del flujo de verificación social anterior)
  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_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>'

Vincular una nueva clave de paso WebAuthn

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 1: Agrega el origen de tu aplicación front-end a los orígenes relacionados

Las claves de paso WebAuthn están vinculadas a un nombre de host específico llamado Relying Party ID (RP ID). Solo las aplicaciones alojadas en el origen del RP ID pueden registrar o autenticar con esas claves de paso.

Dado que tu aplicación front-end llama a la Account API desde un dominio diferente al de las páginas de autenticación de Logto, necesitas configurar Related Origins para permitir operaciones de claves de paso entre dominios.

Cómo determina Logto el RP ID:

Configuración predeterminada: Si solo usas el dominio predeterminado de Logto https://[tenant-id].logto.app, el RP ID es [tenant-id].logto.app
Dominio personalizado: Si has configurado un dominio personalizado como https://auth.example.com, el RP ID se convierte en auth.example.com

Configurar Orígenes Relacionados:

Usa el endpoint PATCH /api/account-center para agregar el origen de la aplicación front-end. Por ejemplo, si el centro de cuentas de tu aplicación se ejecuta en 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"]}'

nota:

WebAuthn admite hasta 5 etiquetas eTLD+1 únicas para Orígenes Relacionados. El eTLD+1 (dominio de nivel superior efectivo más una etiqueta) es la parte del dominio registrable. Por ejemplo:

https://example.com, https://app.example.com, y https://auth.example.com cuentan como una etiqueta (example.com)
https://shopping.com, https://shopping.co.uk, y https://shopping.co.jp también cuentan como una etiqueta (shopping)
https://example.com y https://another.com cuentan como dos etiquetas

Si necesitas admitir más de 5 dominios diferentes como Orígenes Relacionados, consulta la documentación de Solicitudes de Orígenes Relacionados para obtener detalles.

Paso 2: Solicitar nuevas opciones de registro

Usa el endpoint POST /api/verifications/web-authn/registration para solicitar el registro de una nueva clave de paso. Logto permite que cada cuenta de usuario registre múltiples claves de paso.

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 3: Registrar la clave de paso en el navegador local

Toma @simplewebauthn/browser como ejemplo, puedes usar la función startRegistration para registrar la clave de paso 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 uso posterior

Paso 4: Verificar el registro de la clave de paso

Usa el endpoint POST /api/verifications/web-authn/registration/verify para verificar el registro de la clave de paso.

Este paso verifica la firma criptográfica generada por el autenticador para asegurar que la clave de paso fue creada legítimamente y no ha sido alterada durante la transmisión.

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 5: Vincular la clave de paso

Finalmente, puedes vincular la clave de paso a la cuenta del usuario usando el 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: 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 claves de paso WebAuthn existentes

Para gestionar claves de paso WebAuthn existentes, puedes usar el endpoint GET /api/my-account/mfa-verifications para obtener las claves de paso 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 como:

[
  {
    "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 paso WebAuthn.
name: el nombre de la clave de paso, campo opcional.
agent: el agente de usuario de la clave de paso.

Actualiza el nombre de la clave de paso usando el 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":"..."}'

Elimina la clave de paso usando el 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 un nuevo TOTP

nota:

Recuerda habilitar MFA y TOTP primero.

nota:

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

Paso 1: Generar un secreto TOTP

Usa el endpoint POST /api/my-account/mfa-verifications/totp-secret/generate para generar un secreto 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'

El cuerpo de la respuesta sería como:

{
  "secret": "..."
}

Paso 2: Mostrar el secreto TOTP al usuario

Usa el secreto para generar un código QR o muéstralo directamente al usuario. El usuario debe agregarlo a su aplicación de autenticación (como Google Authenticator, Microsoft Authenticator o Authy).

El formato URI para el código QR debe ser:

otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

Ejemplo:

otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

Paso 3: Vincular el factor TOTP

Después de que el usuario haya agregado el secreto a su aplicación de autenticación, necesita verificarlo y vincularlo a su cuenta. Usa el endpoint POST /api/my-account/mfa-verifications para vincular el factor 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: 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: debe ser Totp.
secret: el secreto TOTP generado en el paso 1.

nota:

Un usuario solo puede tener un factor TOTP a la vez. Si el usuario ya tiene un factor TOTP, intentar agregar otro resultará en un error 422.

Gestionar códigos de respaldo

nota:

Recuerda habilitar MFA y códigos de respaldo primero.

nota:

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

Paso 1: Generar nuevos códigos de respaldo

Usa el endpoint POST /api/my-account/mfa-verifications/backup-codes/generate para generar un nuevo conjunto de 10 códigos de respaldo.

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'

El cuerpo de la respuesta sería como:

{
  "codes": ["...", "...", "..."]
}

Paso 2: Mostrar códigos de respaldo al usuario

Antes de vincular los códigos de respaldo a la cuenta del usuario, debes mostrarlos al usuario e instruirlo para que:

Descargue o anote estos códigos inmediatamente
Los almacene en un lugar seguro
Entienda que cada código solo se puede usar una vez
Sepa que estos códigos son su último recurso si pierde acceso a sus métodos MFA principales

Debes mostrar los códigos en un formato claro y fácil de copiar y considerar proporcionar una opción de descarga (por ejemplo, como un archivo de texto o PDF).

Paso 3: Vincular códigos de respaldo a la cuenta del usuario

Usa el endpoint POST /api/my-account/mfa-verifications para vincular los códigos de respaldo a la cuenta del usuario.

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: 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: debe ser BackupCode.
codes: el array de códigos de respaldo generados en el paso anterior.

nota:

Un usuario solo puede tener un conjunto de códigos de respaldo a la vez. Si se han utilizado todos los códigos, el usuario necesita generar y vincular nuevos códigos.
Los códigos de respaldo no pueden ser el único factor MFA. El usuario debe tener al menos otro factor MFA (como WebAuthn o TOTP) habilitado.
Cada código de respaldo solo se puede usar una vez.

Ver códigos de respaldo existentes

Para ver los códigos de respaldo existentes y su estado de uso, usa el 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>'

El cuerpo de la respuesta sería como:

{
  "codes": [
    {
      "code": "...",
      "usedAt": null
    },
    {
      "code": "...",
      "usedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

code: el código de respaldo.
usedAt: la marca de tiempo cuando se usó el código, null si aún no se ha usado.

Gestionar sesiones de usuario

Listar sesiones activas

Para listar las sesiones activas del usuario, puedes usar el endpoint GET /api/my-account/sessions.

nota:

Se requiere el alcance UserScope.Sessions para acceder a este endpoint.
El campo Sessions en la configuración del centro de cuentas debe estar configurado en ReadOnly o Edit.

curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Revocar sesión por ID de sesión

Para revocar una sesión específica, usa el endpoint DELETE /api/my-account/sessions/{sessionId}.

nota:

Se requiere el alcance UserScope.Sessions para acceder a este endpoint.
El campo Sessions en la configuración del centro de cuentas debe estar configurado en Edit.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Parámetros de consulta opcionales:

revokeGrantsTarget: Opcionalmente especifica el objetivo de las concesiones a revocar junto con la sesión. Valores posibles:
- all: Revoca todas las concesiones asociadas con la sesión.
- firstParty: Revoca solo las concesiones de aplicaciones de primera parte asociadas con la sesión. (Recomendado para la mayoría de los casos de uso, ya que revoca el acceso para tu propia aplicación mientras mantiene intactas las concesiones de aplicaciones de terceros, proporcionando una mejor experiencia de usuario).
- no especificado: El comportamiento predeterminado revoca las concesiones que no tienen el alcance offline_access, lo que generalmente significa revocar concesiones que no son de token de actualización para la sesión.

Gestionar aplicaciones autorizadas por el usuario (concesiones)

Usa las APIs de aplicaciones autorizadas por el usuario (concesiones) cuando los usuarios necesiten revisar y revocar aplicaciones autorizadas desde su página de configuración de cuenta.

nota:

Las APIs de concesiones de aplicaciones comparten el mismo modelo de permisos que las APIs de sesiones.
Se requiere el alcance UserScope.Sessions.
El campo Sessions en la configuración del centro de cuentas debe estar habilitado:
- ReadOnly o Edit para listar concesiones.
- Edit para revocar concesiones.

Listar concesiones de aplicaciones activas

Para listar las concesiones de aplicaciones activas del usuario actual, usa el endpoint GET /api/my-account/grants.

curl https://[tenant-id].logto.app/api/my-account/grants \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Parámetro de consulta opcional:

appType=firstParty: Devuelve solo concesiones de aplicaciones de primera parte.
appType=thirdParty: Devuelve solo concesiones de aplicaciones de terceros.
Omitir appType: Devuelve todas las concesiones activas.

curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Revocar concesión de aplicación por ID de concesión

Para revocar una concesión de aplicación específica, usa el endpoint DELETE /api/my-account/grants/{grantId}.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

Cuando se revoca una concesión, los tokens de acceso opacos y los tokens de actualización emitidos previamente para esa concesión se invalidan.

¿Qué es Logto Account API?​

Cómo habilitar Account API​

Cómo acceder a Account API​

Obtener un token de acceso​

Acceder a Account API usando el token de acceso​

Gestionar información básica de la cuenta​

Recuperar información de la cuenta de usuario​

Actualizar información básica de la cuenta​

Gestionar identificadores y otra información sensible​

Obtener un ID de registro de verificación​

Verificar la contraseña del usuario​

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

Enviar solicitud con ID de registro de verificación​

Actualizar la contraseña del usuario​

Actualizar o vincular un nuevo correo electrónico​

Eliminar el correo electrónico del usuario​

Gestionar teléfono​

Vincular una nueva conexión social​

Eliminar una conexión social​

Vincular una nueva clave de paso WebAuthn​

Gestionar claves de paso WebAuthn existentes​

Vincular un nuevo TOTP​

Gestionar códigos de respaldo​

Gestionar sesiones de usuario​

Gestionar aplicaciones autorizadas por el usuario (concesiones)​

¿Qué es Logto Account API?

Cómo habilitar Account API

Cómo acceder a Account API

Obtener un token de acceso

Acceder a Account API usando el token de acceso

Gestionar información básica de la cuenta

Recuperar información de la cuenta de usuario

Actualizar información básica de la cuenta

Gestionar identificadores y otra información sensible

Obtener un ID de registro de verificación

Verificar la contraseña del usuario

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

Enviar solicitud con ID de registro de verificación

Actualizar la contraseña del usuario

Actualizar o vincular un nuevo correo electrónico

Eliminar el correo electrónico del usuario

Gestionar teléfono

Vincular una nueva conexión social

Eliminar una conexión social

Vincular una nueva clave de paso WebAuthn

Gestionar claves de paso WebAuthn existentes

Vincular un nuevo TOTP

Gestionar códigos de respaldo

Gestionar sesiones de usuario

Gestionar aplicaciones autorizadas por el usuario (concesiones)