Configuración de cuenta mediante Account API

¿Qué es la Account API de Logto?

La Account API de Logto 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 estará disponible próximamente.
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 en el encabezado Authorization como Bearer <access_token>.

Con la Account API de Logto, 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 enumeran a continuación:

Recuperar el perfil de usuario
Actualizar el perfil de usuario
Actualizar la contraseña del usuario
Actualizar identidades del 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 (grants)

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

nota:

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

Cómo habilitar la Account API

Navega a Consola > Inicio de sesión y cuenta > Centro de cuentas.

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 la ventana de Autenticación reciente (de 1 a 120 minutos; 10 minutos por defecto) y 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, passkeys, MFA y tokens de acceso personal.
- Las operaciones sensibles requieren autenticación reciente del usuario desde una aplicación de primera parte—un token de acceso cuyo acr cumpla con urn:logto:acr:1fa dentro de la ventana de autenticación reciente configurada (ver Autenticación step-up OIDC).
- Para usar passkeys WebAuthn para MFA, agrega los dominios de tu aplicación front-end a WebAuthn Related Origins para que el centro de cuentas y la experiencia de inicio de sesión puedan compartir passkeys. Consulta Vincular una nueva passkey WebAuthn.
Campos de perfil:
- Los campos incluyen: nombre de usuario, nombre, avatar, perfil (otros atributos estándar de perfil) y datos personalizados.
- Los usuarios finales pueden editar estos campos sin verificación adicional, excepto username, que también requiere autenticación reciente del usuario.
Bóveda secreta:
- Para conectores sociales y empresariales OIDC u OAuth, la bóveda secreta de Logto 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 estará 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 en dispositivos específicos.
- Este mismo permiso de campo Sessions también controla las APIs de aplicaciones autorizadas por el usuario (grants) (ver y revocar grants).
- Acceder a la gestión de sesiones y grants requiere la misma autenticación reciente del usuario que los campos de seguridad.

Cómo acceder a la 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 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
    UserScope.Sessions, // Para gestionar sesiones de usuario y grants 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 puede usarse para acceder a la Account API.

Si no estás usando el SDK oficial, debes establecer el resource vacío en 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

Para obtener los datos del 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 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, 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, las operaciones sensibles de la Account API requieren autenticación reciente del usuario desde una aplicación de primera parte: el token de acceso debe llevar acr cumpliendo con urn:logto:acr:1fa y un auth_time dentro de la ventana de Autenticación reciente de tu tenant (600 segundos / 10 minutos por defecto, configurable de 60 a 7,200 segundos).

Cuando el token de acceso no tiene urn:logto:acr:1fa o ha superado la ventana, la Account API devuelve 401 Unauthorized con un encabezado RFC 9470 WWW-Authenticate (error="insufficient_user_authentication", acr_values="urn:logto:acr:1fa", max_age="<window>"). Inicia una solicitud de autenticación step-up OIDC con esos parámetros y vuelve a intentar la llamada con el nuevo token de acceso emitido.

nota:

Vincular un nuevo correo electrónico, número de teléfono, identidad social o passkey WebAuthn también requiere demostrar la propiedad de ese nuevo identificador o factor a través de la Verification API y pasar newIdentifierVerificationRecordId en el cuerpo de la solicitud, como se muestra en cada sección a continuación.

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 '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 Consola > Seguridad > Política de contraseñas. Logto devuelve resultados de validación detallados y mensajes de error si la contraseña no cumple 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.

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

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

tip:

Al igual que los correos electrónicos recopilados durante el registro, cualquier correo vinculado a través de la Account API debe pasar la verificación de la lista de bloqueo que configuraste en Consola > Seguridad > Lista de bloqueo. 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>'

Gestionar teléfono

nota:

Para usar este método, necesitas configurar el conector 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 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 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 el callback.
state: El estado que se devolverá después de que el usuario autorice la aplicación; es una cadena aleatoria que se utiliza 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 'content-type: application/json' \
  --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>'

Vincular una nueva passkey 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 passkeys WebAuthn están vinculadas a un hostname específico llamado Relying Party ID (RP ID). Solo las aplicaciones alojadas en el origen del RP ID pueden registrar o autenticar con esas passkeys.

Como 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 passkey entre orígenes.

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

Configura Related Origins:

Usa el endpoint PATCH /api/account-center para agregar el origen de tu aplicación front-end. Por ejemplo, si el centro de cuentas de tu app 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 Related Origins. El eTLD+1 (dominio de nivel superior efectivo más una etiqueta) es la parte registrable del dominio. 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 Related Origins, consulta la documentación de Related Origin Requests para más detalles.

Paso 2: Solicita nuevas opciones de registro

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

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: Registra la passkey en el navegador local

Usando @simplewebauthn/browser como ejemplo, puedes usar la función startRegistration para registrar la passkey 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 usarla después

Paso 4: Verifica el registro de la passkey

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

Este paso verifica la firma criptográfica generada por el autenticador para asegurar que la passkey fue creada legítimamente y no ha sido manipulada 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: Vincula la passkey

Finalmente, puedes vincular la passkey 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 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'

type: el tipo del factor MFA, actualmente solo se admite WebAuthn.
newIdentifierVerificationRecordId: el ID de registro de verificación devuelto por el servidor en el paso 1.

Gestionar passkeys WebAuthn existentes

Para gestionar passkeys WebAuthn existentes, puedes usar el endpoint GET /api/my-account/mfa-verifications para obtener las passkeys 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 passkey WebAuthn.
name: el nombre de la passkey, campo opcional.
agent: el user agent de la passkey.

Actualiza el nombre de la passkey 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 'content-type: application/json' \
  --data-raw '{"name":"..."}'

Elimina la passkey 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>'

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: Genera 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 así:

{
  "secret": "..."
}

Paso 2: Muestra 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 autenticadora (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:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

Paso 3: Vincula el factor TOTP

Después de que el usuario haya agregado el secreto a su aplicación autenticadora, debe 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 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'

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.

Reemplazar un TOTP existente

Si el usuario ya tiene un factor TOTP configurado, puedes reemplazarlo por uno nuevo usando el endpoint PUT /api/my-account/mfa-verifications/totp. Esta es una operación idempotente que elimina el TOTP existente y vincula uno nuevo.

nota:

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

Paso 1: Genera un nuevo secreto TOTP

Usa el endpoint POST /api/my-account/mfa-verifications/totp-secret/generate para generar un nuevo secreto TOTP y luego muéstralo al usuario como se describe en Vincular un nuevo TOTP.

Paso 2: Reemplaza el factor TOTP

curl -X PUT https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"secret":"...","code":"..."}'

secret: el nuevo secreto TOTP generado en el paso 1.
code: el código TOTP generado a partir del nuevo secreto para confirmar la vinculación.

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: Genera 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 así:

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

Paso 2: Muestra los códigos de respaldo al usuario

Antes de vincular los códigos de respaldo a la cuenta del usuario, debes mostrárselos y pedirle que:

Descargue o anote estos códigos inmediatamente
Los almacene en un lugar seguro
Entienda que cada código solo puede usarse 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 ofrecer una opción de descarga (por ejemplo, como archivo de texto o PDF).

Paso 3: Vincula los 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 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'

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 usado todos los códigos, el usuario debe 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 puede usarse 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 así:

{
  "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 la configuración de verificación en 2 pasos

nota:

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

Los usuarios finales pueden activar o desactivar la verificación en 2 pasos para su cuenta. Un caso de uso común es cuando un usuario ha configurado factores MFA (como passkeys) pero solo quiere usarlos para iniciar sesión y no como un paso de verificación adicional; desactivar la verificación en 2 pasos le permite omitir el aviso de MFA durante el inicio de sesión mientras mantiene sus factores MFA intactos. Esto se controla mediante la configuración skipMfaOnSignIn por usuario.

Obtener la configuración actual de MFA

Usa el endpoint GET /api/my-account/mfa-settings para recuperar la configuración actual de verificación en 2 pasos del usuario.

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

El cuerpo de la respuesta sería así:

{
  "skipMfaOnSignIn": false
}

Actualizar la configuración de MFA

Para habilitar o deshabilitar la verificación en 2 pasos, usa el endpoint PATCH /api/my-account/mfa-settings.

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-settings \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"skipMfaOnSignIn":true}'

skipMfaOnSignIn: establece en true para desactivar la verificación en 2 pasos para el usuario, o en false para activarla.

nota:

Esta configuración solo tiene efecto cuando la política de MFA está establecida en Opcional. Si MFA es Obligatorio o Adaptativo, la configuración skipMfaOnSignIn será ignorada y MFA será obligatorio.

Gestionar sesiones de usuario

Listar sesiones activas

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

nota:

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

curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -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:

El alcance UserScope.Sessions es necesario para acceder a este endpoint.
El campo Sessions en la configuración del centro de cuentas debe estar en Edit.

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

Parámetros de consulta opcionales:

revokeGrantsTarget: Opcionalmente especifica el objetivo de los grants a revocar junto con la sesión. Valores posibles:
- all: Revoca todos los grants asociados con la sesión.
- firstParty: Revoca solo los grants de aplicaciones de primera parte asociados con la sesión. (Recomendado para la mayoría de los casos, ya que revoca el acceso para tu propia app mientras mantiene los grants de apps de terceros intactos, proporcionando una mejor experiencia de usuario.)
- sin especificar: El comportamiento predeterminado revoca los grants que no tienen el alcance offline_access, lo que normalmente significa revocar grants sin refresh token para la sesión.

Gestionar aplicaciones autorizadas por el usuario (grants)

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

nota:

Las APIs de grants 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 grants.
- Edit para revocar grants.

Listar grants de aplicaciones activas

Para listar los grants 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 'content-type: application/json'

Parámetro de consulta opcional:

appType=firstParty: Devuelve solo grants de aplicaciones de primera parte.
appType=thirdParty: Devuelve solo grants de aplicaciones de terceros.
Omitir appType: Devuelve todos los grants activos.

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

Revocar grant de aplicación por ID de grant

Para revocar un grant de aplicación específico, 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 'content-type: application/json'

Cuando se revoca un grant, los tokens de acceso opacos y los refresh tokens emitidos previamente para ese grant quedan invalidados.

¿Qué es la Account API de Logto?​

Cómo habilitar la Account API​

Cómo acceder a la Account API​

Obtener un token de acceso​

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

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 passkey WebAuthn​

Gestionar passkeys WebAuthn existentes​

Vincular un nuevo TOTP​

Reemplazar un TOTP existente​

Gestionar códigos de respaldo​

Gestionar la configuración de verificación en 2 pasos​

Gestionar sesiones de usuario​

Gestionar aplicaciones autorizadas por el usuario (grants)​

¿Qué es la Account API de Logto?

Cómo habilitar la Account API

Cómo acceder a la Account API

Obtener un token de acceso

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

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 passkey WebAuthn

Gestionar passkeys WebAuthn existentes

Vincular un nuevo TOTP

Reemplazar un TOTP existente

Gestionar códigos de respaldo

Gestionar la configuración de verificación en 2 pasos

Gestionar sesiones de usuario

Gestionar aplicaciones autorizadas por el usuario (grants)