Saltar al contenido principal
La autenticación es una función nueva. La página de inicio de sesión alojada ejecuta todos los métodos de esta página. Los endpoints JSON que se indican aquí son para los equipos que crean sus propias pantallas de inicio de sesión (sign_in_ui: "own").
Activa un método con PUT methods/{name}/ y {"enabled": true} en la API de gestión de autenticación de tu aplicación, o desde la consola. El inicio de sesión alojado muestra solo los métodos que hayas activado. Cada una de las siguientes llamadas JSON empieza con un transaction de POST authorize/. Esa transacción dura 10 minutos. Un inicio de sesión correcto devuelve {code, redirect_uri, state}. Canjea el código en POST token/ en un plazo de 60 segundos (consulta tokens y JWKS). En lugar de un código, una llamada de inicio de sesión puede devolver uno de estos pasos. Completa el paso y después recibirás el código.

​
Contraseña

POST password/ recibe transaction, email y password.
  • Una contraseña debe cumplir tu password_min_length (8, 10, 12 o 14 caracteres; 10 por defecto). Las contraseñas comunes y las formadas solo por números se rechazan con password_policy. Cuando la comprobación de contraseñas comprometidas está activada, una contraseña comprometida conocida se rechaza con password_breached.
  • Solo las personas con un correo electrónico verificado pueden iniciar sesión con contraseña.
  • Una contraseña incorrecta, un correo electrónico desconocido, un correo electrónico no verificado, una cuenta bloqueada temporalmente y una cuenta bloqueada reciben todos la misma respuesta: 400 {"error": "invalid_credentials"}. Tu interfaz no puede saber cuál de ellos fue, y un atacante tampoco.

​
Registro

El registro verifica primero el correo electrónico. Invoca POST email/start/ con purpose: "signup", email y password, y después a POST email/complete/ con el código. La cuenta se crea con el correo electrónico verificado.
  • signup_policy decide quién puede registrarse: anyone, invited (solo con un enlace de invitación) o allowed_domains.
  • Con allow_subaddresses: false (el valor por defecto), se rechaza una dirección con + en la parte local.
  • Cuando tu marca define enlaces a los términos o a la política de privacidad, el formulario de registro alojado pide a la persona que los acepte.

​
Código por correo electrónico

POST email/start/ recibe transaction, purpose (login o signup) y email, y devuelve 202 {challenge, expires_in: 600}. La persona recibe un código de 6 dígitos que dura 10 minutos. POST email/complete/ recibe transaction, purpose, challenge y code. Tienes 5 intentos; después, la persona debe solicitar un código nuevo. La página alojada ofrece un código nuevo pasados 30 segundos. Un código de inicio de sesión para una dirección sin cuenta crea una cuando tu signup_policy lo permite. Así funciona el registro sin contraseña.

​
Enlace mágico

La página alojada envía un enlace de inicio de sesión que dura 15 minutos. Sigue vinculado a la transacción PKCE original, por lo que el enlace solo funciona en el flujo que lo inició. La persona confirma el inicio de sesión en la página que abre el enlace. No hay ningún endpoint JSON para los enlaces mágicos.

​
Código telefónico

POST phone/start/ recibe transaction, phone y un channel opcional (sms, el valor por defecto, o whatsapp). El número se normaliza al formato E.164. Devuelve 202 {challenge, expires_in: 600}. POST phone/complete/ recibe transaction, challenge y el code de 6 dígitos. Tienes 5 intentos.
  • Los códigos telefónicos se envían mediante la verificación telefónica de Didit. Activa el método con el workflow_id de un flujo que incluya la verificación telefónica.
  • Un primer inicio de sesión por teléfono crea una cuenta solo cuando signup_policy es anyone.
  • Si la entrega falla, la solicitud devuelve 503 {"error": "delivery_unavailable"}.

​
Passkeys

Las passkeys usan WebAuthn. La parte de confianza (relying party) es el origen de inicio de sesión de tu aplicación. Didit solicita una credencial detectable (resident key) y siempre exige la verificación del usuario, como una huella dactilar, el rostro o el PIN del dispositivo. Didit no solicita atestación.
  • Un desafío de passkey dura 5 minutos.
  • Para añadir una passkey se necesita una sesión creada en los últimos 5 minutos. De lo contrario, la llamada devuelve 403 {"error": "reauthentication_required"}. Primero haz que la persona vuelva a iniciar sesión.
  • Un inicio de sesión con passkey cuenta como autenticación multifactor.
  • Después del registro, la página alojada ofrece añadir una passkey (passkeys/setup/begin/ y passkeys/setup/complete/).
  • Las apps de Android registradas en la aplicación pueden usar las mismas passkeys.

​
Inicio de sesión social

El inicio de sesión con Google, Microsoft, Apple y GitHub usa las credenciales de tu propia aplicación OAuth, que se configuran con PUT methods/{provider}/ y credentials: {client_id, client_secret}. El callback del proveedor está en tu origen de inicio de sesión. La primera vez que alguien inicia sesión con un proveedor, además demuestra que es el titular de la dirección de correo electrónico mediante un código (POST social/email/start/ y POST social/email/verify/). Los inicios de sesión posteriores con ese proveedor omiten este paso. GitHub no puede demostrar un inicio de sesión reciente, por lo que no se ofrece cuando envías prompt=login o max_age.

​
SSO de organización

El SSO de organización permite que la empresa de un cliente inicie sesión a través de su propio proveedor de identidad SAML u OIDC. Configúralo para cada organización cliente en organizations/{id}/sso/ con protocol (saml u oidc), enabled y config.
  • Puedes enviar al equipo de TI del cliente un enlace de configuración válido durante 7 días.
  • Los metadatos de tu proveedor de servicios SAML se publican en {origin}/sso/saml/metadata/.
  • El inicio de sesión alojado determina la conexión a partir del dominio de correo electrónico verificado de la persona, o a partir de organization=<slug> en la URL de inicio de sesión.

​
Didit ID Wallet

Las personas que ya se verificaron con Didit pueden iniciar sesión con su Didit ID Wallet. Este método está siempre activado. El campo verified_identity de la sesión contiene entonces lo que la persona eligió compartir.

​
MFA

El segundo factor es una aplicación de autenticación (TOTP) con códigos de recuperación, o una passkey.
  • mfa_policy decide quién debe usar MFA: optional, everyone u organization_admins (el valor predeterminado). Quien haya registrado una aplicación de autenticación debe usarla siempre.
  • Para registrar una aplicación de autenticación, invoca POST mfa/enroll/ con una sesión reciente (creada en los últimos 5 minutos). Devuelve {challenge, uri}; muestra la uri en forma de código QR. Después, envía el primer código a POST mfa/confirm/. La respuesta contiene 10 códigos de recuperación de un solo uso. Muéstralos una sola vez.
  • Al iniciar sesión, envía un código TOTP o de recuperación a POST mfa/complete/ junto con el challenge. Dispones de 5 intentos. Para usar una passkey en su lugar, invoca POST mfa/passkey/begin/ y POST mfa/passkey/complete/.
  • Los códigos usan intervalos de 30 segundos. Un código que ya se aceptó no puede volver a usarse.
  • Los códigos por SMS y por correo electrónico no están disponibles como segundo factor.

​
Contraseña olvidada y restablecimiento

POST password-reset/start/ recibe email y devuelve 202 {"status": "sent", "expires_in": 1800}. La respuesta es la misma tanto si la dirección tiene una cuenta como si no. El enlace de restablecimiento es válido durante 30 minutos. POST password-reset/complete/ recibe token y password y devuelve {"status": "password_changed"}. Además:
  • elimina un bloqueo,
  • cierra todas las sesiones cuando revoke_on_password_change está activado (el valor predeterminado),
  • invalida los demás códigos y enlaces pendientes de esa persona.

​
Invitaciones

Con signup_policy: "invited", solo las personas invitadas pueden registrarse. Un enlace de invitación es válido durante 7 días y abre la página alojada /invite. Continúa con tokens y JWKS, o consulta protección contra bots para conocer los bloqueos y los desafíos.
Última modificación el 1 de noviembre de 2026