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 otorga a los usuarios finales acceso directo a la API sin necesidad de pasar por la Management API. Aquí tienes los puntos 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 posibilidad 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 complicaciones: ¡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 la cabecera Authorization comoBearer <access_token>
.
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 según 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
],
};
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 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 conocer más sobre las APIs disponibles, visita la Referencia de la Account API de Logto y la Referencia de la Verification API de Logto.
Próximamente estarán disponibles Account APIs dedicadas para las siguientes configuraciones: 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.
Las APIs de gestión de MFA (TOTP y códigos de respaldo) están actualmente en desarrollo y solo disponibles cuando la bandera isDevFeaturesEnabled
está establecida en true
. La gestión de claves WebAuthn está completamente disponible.
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
. 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 contrariofalse
.social
: Conexiones sociales.mfa
: Factores de MFA.
Aprende más sobre los detalles de la API en la Referencia de la Management API de Logto.
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
como 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 las cabeceras 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, 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 con una expiración de 10 minutos (TTL). Esto puede usarse para verificar la identidad del usuario antes de actualizar información sensible. Esto significa que una vez que un usuario verifica exitosamente su identidad mediante 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 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 así:
{
"verificationRecordId": "...",
"expiresAt": "..."
}
Verificar enviando un código de verificación al correo electrónico o teléfono del usuario
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.
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.
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 saber más sobre verificaciones, consulta Verificación de seguridad mediante Account API.
Enviar solicitud con el 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 la cabecera 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":"..."}'
Actualizar o vincular un nuevo correo electrónico
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 '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
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 usar el endpoint DELETE /api/my-account/primary-phone
para eliminar el teléfono del usuario.
Vincular una nueva conexión social
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 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>'
Vincular una nueva clave WebAuthn
Recuerda habilitar MFA y WebAuthn primero.
Para usar este método, necesitas habilitar el campo mfa
en la configuración del centro de cuentas.
Paso 1: Añade el origen de tu app front-end a los orígenes relacionados
Las claves 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 claves.
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 entre orígenes.
Cómo determina Logto el RP ID:
- Configuración por defecto: Si solo usas el dominio por defecto 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 seráauth.example.com
Configura Related Origins:
Usa el endpoint PATCH /api/account-center
para añadir el origen de tu aplicación front-end. Por ejemplo, si el centro de cuentas de tu app corre 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"]}'
Para saber más sobre los orígenes relacionados, consulta la documentación de Related Origin Requests.
Paso 2: Solicita nuevas opciones de registro
Usa el endpoint POST /api/verifications/web-authn/registration
para solicitar el registro de una nueva clave. Logto permite que cada cuenta de usuario registre múltiples claves.
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 clave en el navegador local
Tomando @simplewebauthn/browser
como ejemplo, puedes usar la función startRegistration
para registrar la clave 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 4: Verifica el registro de la clave
Usa el endpoint POST /api/verifications/web-authn/registration/verify
para verificar el registro de la clave.
Este paso verifica la firma criptográfica generada por el autenticador para asegurar que la clave 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 clave
Finalmente, puedes vincular la clave 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, obtenido 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 admiteWebAuthn
.newIdentifierVerificationRecordId
: el ID de registro de verificación devuelto por el servidor en el paso 1.
Gestionar claves WebAuthn existentes
Para gestionar claves WebAuthn existentes, 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 WebAuthn.name
: el nombre de la clave, campo opcional.agent
: el user agent de la clave.
Actualiza el nombre de la clave 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 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
Recuerda habilitar MFA y TOTP primero.
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 añadirlo a su app 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:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=YourApp
Paso 3: Vincula el factor TOTP
Después de que el usuario haya añadido el secreto a su app de autenticación, 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 '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, obtenido 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 serTotp
.secret
: el secreto TOTP generado en el paso 1.
Un usuario solo puede tener un factor TOTP a la vez. Si el usuario ya tiene un factor TOTP, intentar añadir otro resultará en un error 422.
Gestionar códigos de respaldo
Recuerda habilitar MFA y códigos de respaldo primero.
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 recomendarle 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 '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, obtenido 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 serBackupCode
.codes
: el array de códigos de respaldo generados en el paso anterior.
- 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 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 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.