Documentation

Primeros pasos

Authagonal proporciona a cada inquilino un servidor OIDC totalmente compatible con estándares. Cada inquilino obtiene su propia URL de emisor, documento de descubrimiento y endpoints de token — sin infraestructura compartida entre inquilinos. Puedes pasar de cero a un flujo de inicio de sesión funcional en menos de 5 minutos.

Crear un inquilino

Regístrate en authagonal.io y elige un slug para tu inquilino. El slug se convierte en tu dominio de emisor: {slug}.authagonal.io. Después de crear tu cuenta, verifica tu dirección de correo electrónico para activar el inquilino.

Elige un slug único para tu inquilino durante el registro

Registrar un cliente

Navega a Clientes en la barra lateral del portal y haz clic en Crear. Ingresa un clientId y un clientName para tu aplicación. Luego configura al menos una URI de redirección — aquí es donde se envían los usuarios después de autenticarse. Por ejemplo: https://app.example.com/callback.

Registrar un nuevo cliente OAuth en el portal

Tu primer inicio de sesión

La forma más rápida de integrar es con oidc-client-ts, una biblioteca de cliente OIDC ligera para aplicaciones JavaScript y TypeScript.

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

Si prefieres un enfoque mínimo sin biblioteca, puedes usar el flujo estándar de código de autorización OAuth 2.0 con fetch simple:

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token, tokens.refresh_token

La página de inicio de sesión predeterminada para tu inquilino

Panel de control

El panel de control del portal te ofrece una visión en tiempo real de tu inquilino. Presenta las métricas más importantes — crecimiento de usuarios, actividad de autenticación y navegación rápida a todas las funcionalidades del portal.

Resumen

En la parte superior del panel de control verás un mensaje de bienvenida junto con tu recuento total actual de usuarios. Debajo, un gráfico de Usuarios activos diarios muestra un historial de 7 días de usuarios únicos que se autenticaron cada día, dándote un pulso rápido sobre las tendencias de interacción.

La pantalla principal del panel de control con gráfico de DAU y resumen de actividad

Métricas de actividad

El panel de métricas de actividad muestra cuatro tarjetas de estadísticas que resumen eventos clave de autenticación:

• Inicios de sesión exitosos — flujos de autenticación completados en total
• Inicios de sesión fallidos — credenciales incorrectas, cuentas bloqueadas o rechazos por política
• Usuarios activos — usuarios únicos que se autenticaron en el período seleccionado
• Operaciones SCIM — eventos de aprovisionamiento de usuarios y grupos desde IdPs conectados

Usa los filtros de rango de tiempo para alternar entre 24 horas, 3 días, 7 días y 30 días. Todas las tarjetas de estadísticas y gráficos se actualizan para reflejar la ventana seleccionada.

Métricas de actividad con rango de tiempo configurable

Navegación rápida

Debajo del panel de métricas, las tarjetas de navegación enlazan directamente a cada funcionalidad principal: Clientes, Usuarios, Grupos, Roles, SSO, SCIM, Marca y Configuración. Cada tarjeta muestra una breve descripción para que los nuevos miembros del equipo puedan orientarse rápidamente.

Clientes

Los clientes OAuth representan las aplicaciones que autentican usuarios a través de tu inquilino. Cada cliente tiene su propia configuración de URIs de redirección, alcances, tipos de concesión, duraciones de tokens y política de MFA.

Lista de clientes

La página de Clientes muestra una tabla con todos los clientes registrados. Cada fila muestra el clientId, nombre para mostrar, tipos de concesión permitidos como insignias de colores y si PKCE está habilitado. Haz clic en cualquier fila para abrir el editor de configuración completo.

Lista de clientes con insignias de tipo de concesión e indicadores de PKCE

Crear un cliente

Haz clic en Crear cliente para registrar una nueva aplicación. Necesitas proporcionar dos campos:

• clientId — un identificador único para el cliente (por ejemplo, my-spa)
• clientName — un nombre para mostrar legible por humanos

Registrar un nuevo cliente OAuth

Eliminar un cliente

Para eliminar un cliente, abre la configuración del cliente y haz clic en el botón Eliminar cliente en la parte inferior de la página. Se te pedirá confirmar antes de que el cliente sea eliminado permanentemente. Todas las sesiones activas y tokens del cliente eliminado se invalidan inmediatamente.

Referencia de configuración de cliente

Cada cliente tiene un conjunto completo de opciones de configuración organizadas en varias secciones.

Configuración general

URIs

Los campos de URI utilizan una entrada de etiquetas — escribe un valor y presiona Enter o coma para añadirlo. Haz clic en la X de cualquier etiqueta para eliminarla.

Campos de entrada de etiquetas para configurar URIs

Alcances y tipos de concesión

Duraciones de tokens

Configurar duraciones de tokens por cliente

URIs de logout

Los clientes pueden registrar URIs de logout tanto back-channel como front-channel. Ambas son opcionales — configura las que coincidan con cómo tu aplicación limpia su sesión.

Política de MFA

Cada cliente puede anular la política de MFA a nivel de inquilino con una configuración por cliente. El menú desplegable de política de MFA ofrece tres opciones:

Anulación de política de MFA por cliente

SSO empresarial

El SSO empresarial permite que tus clientes traigan su propio proveedor de identidad. Authagonal soporta tanto la federación SAML 2.0 como OIDC con enrutamiento basado en dominio, para que los usuarios sean dirigidos automáticamente al IdP correcto según su dirección de correo electrónico.

Enrutamiento SSO basado en dominio

Conexiones SAML 2.0

Para crear una conexión SAML, navega a la página de SSO y selecciona la pestaña SAML. Proporciona lo siguiente:

Cuando guardas la conexión, Authagonal obtiene el documento de metadatos e importa el certificado de firma del IdP, la URL del endpoint SSO y el formato del identificador de nombre. Los metadatos se actualizan periódicamente para incorporar las rotaciones de certificados.

Crear una conexión SSO SAML 2.0

Conexiones OIDC

Para crear una conexión de federación OIDC, selecciona la pestaña OIDC y proporciona:

Crear una conexión de federación OIDC

Enrutamiento de dominio

El enrutamiento de dominio redirige automáticamente a los usuarios al proveedor de identidad correcto según el dominio de su correo electrónico. Cuando un usuario ingresa su correo en la página de inicio de sesión, Authagonal verifica si la parte del dominio (por ejemplo, acme.com) coincide con alguna conexión SSO configurada. Si coincide, el usuario es redirigido de forma transparente al IdP de su organización.

El enrutamiento de dominio mapea dominios de correo electrónico a proveedores de identidad

Aprovisionamiento JIT

Por defecto, cuando un usuario inicia sesión a través de SSO por primera vez y no existe ya en tu inquilino, Authagonal crea su cuenta automáticamente (aprovisionamiento Just-In-Time). Esto se puede deshabilitar por conexión marcando Deshabilitar aprovisionamiento JIT al crear o editar la conexión.

Cuando el aprovisionamiento JIT está deshabilitado, solo los usuarios que han sido pre-aprovisionados — a través de SCIM, la página de Usuarios del portal o la API — pueden iniciar sesión a través de esa conexión. Los usuarios desconocidos reciben un error access_denied y son dirigidos a contactar a su administrador.

Usuarios

La página de Usuarios te permite gestionar todos los usuarios finales en tu inquilino. Puedes buscar usuarios, ver sus detalles, crear nuevas cuentas y ver cómo fue aprovisionado cada usuario.

Búsqueda y paginación

La barra de búsqueda admite filtrado por dirección de correo electrónico o ID de usuario. La búsqueda tiene un retardo de 300ms para que los resultados se actualicen mientras escribes sin sobrecargar la API. Los resultados están paginados a 50 usuarios por página — usa los controles de navegación en la parte inferior de la tabla para moverte entre páginas.

Tabla de usuarios

La tabla de usuarios muestra las siguientes columnas para cada usuario:

La lista de usuarios con barra de búsqueda y paginación

Crear usuarios

Haz clic en Crear usuario para añadir un nuevo usuario local. El formulario requiere:

Crear un nuevo usuario local

Detalle del usuario

Haz clic en cualquier fila de la lista de usuarios para abrir su página de detalle. Desde ahí puedes editar datos de perfil, gestionar roles, restablecer MFA, revisar atributos personalizados y eliminar al usuario.

Perfil

Edita correo electrónico, nombre/apellidos, teléfono, empresa, ID externo y el indicador de activo del usuario. Los cambios de correo deben permanecer únicos en el tenant; la API devuelve email_in_use si ya está en uso.

Roles

Asigna y retira roles definidos en la página Roles. La pertenencia a roles se incluye en los tokens ID y de acceso cuando el cliente tiene activado includeRolesInTokens.

Autenticación multifactor

Consulta todas las credenciales MFA registradas para el usuario — aplicación autenticadora (TOTP), WebAuthn/passkeys y códigos de recuperación — cada una con marcas de tiempo de registro y último uso. Elimina credenciales individuales o restablece todo MFA. Restablecer obliga al usuario a volver a registrarse en el próximo inicio de sesión.

Atributos personalizados

Datos clave/valor arbitrarios asociados al usuario. Las claves deben ser únicas. Los atributos se exponen vía la API de perfil de usuario y SCIM, y pueden mapearse a claims del token de acceso configurando los userClaims de un scope personalizado.

Eliminar usuario

Elimina permanentemente al usuario y todas sus credenciales MFA. Escribe el correo del usuario para confirmar — no hay deshacer.

Grupos

Los grupos te permiten organizar usuarios e incluir la membresía de grupo en los tokens. Los grupos pueden crearse manualmente en el portal o aprovisionarse automáticamente a través de SCIM desde un proveedor de identidad externo.

Lista de grupos

La página de Grupos muestra todos los grupos en tu inquilino con la siguiente información:

Lista de grupos con indicadores de origen

Crear un grupo

Haz clic en Crear grupo e ingresa un displayName para el grupo. Los nombres de grupo deben ser descriptivos y únicos dentro de tu inquilino (por ejemplo, "Engineering", "Billing Admins", "Beta Testers").

Detalle del grupo y miembros

Haz clic en cualquier grupo para abrir la vista de detalle. Aquí puedes ver todos los miembros actuales y gestionar la membresía:

• Añadir miembros — Ingresa un ID de usuario para añadir un usuario al grupo.
• Eliminar miembros — Haz clic en el botón de eliminar junto a cualquier miembro para eliminarlo individualmente.

Gestionar la membresía del grupo en la vista de detalle

Grupos en tokens

Cuando includeGroupsInTokens está habilitado en un cliente, el token de ID incluye un claim groups que contiene las membresías de grupo del usuario. Cada entrada incluye el id y name del grupo:

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "groups": [
    { "id": "grp-001", "name": "Engineering" },
    { "id": "grp-002", "name": "Beta Testers" }
  ]
}

Roles

Los roles soportan el control de acceso basado en roles (RBAC) en tu aplicación. Define roles en Authagonal, asígnalos a usuarios y usa el claim roles en los tokens para aplicar la autorización en la lógica de tu aplicación.

Gestionar roles

La página de Roles muestra una tabla con todos los roles definidos con edición en línea. Cada rol tiene:

Crear un rol

Haz clic en Crear rol y proporciona un nombre y una descripción. Los nombres de los roles deben ser concisos y seguir una convención de nomenclatura consistente en tu aplicación (por ejemplo, minúsculas con guiones: billing-admin).

Edición en línea

Los roles soportan edición en línea directamente en la tabla. Haz clic en el icono de lápiz en cualquier rol para entrar en modo de edición — los campos de nombre y descripción se vuelven editables. Modifica los valores y luego haz clic en el icono de marca de verificación para guardar. Los cambios entran en vigor inmediatamente.

Eliminar un rol

Haz clic en el icono de eliminar en cualquier rol para eliminarlo. Se te pedirá confirmar antes de que el rol sea eliminado permanentemente. Eliminar un rol no invalida retroactivamente los tokens existentes — el rol estará ausente de los nuevos tokens emitidos después de la eliminación.

Edición en línea de roles en la tabla de roles

Roles en tokens

Los roles asignados a un usuario se incluyen como un claim roles en el token de ID. Tu aplicación puede leer este claim para tomar decisiones de autorización:

{
  "sub": "user-123",
  "email": "jane@acme.com",
  "roles": ["admin", "billing-admin"]
}

Aprovisionamiento SCIM

SCIM 2.0 (System for Cross-domain Identity Management) permite el aprovisionamiento automático de usuarios y grupos desde proveedores de identidad empresariales como Okta, Azure AD, OneLogin y JumpCloud. Una vez configurado, las cuentas de usuario y las membresías de grupo se sincronizan automáticamente desde el IdP ascendente a tu inquilino de Authagonal.

Sincronización del ciclo de vida de usuarios SCIM con aprovisionamiento descendente

Pasos de configuración

Sigue estos pasos para habilitar el aprovisionamiento SCIM para un cliente:

1. Selecciona la aplicación cliente — Elige el cliente OAuth con el que se asociará el aprovisionamiento SCIM.
2. Genera un token SCIM — Proporciona una descripción y un período de expiración en días, luego genera el token.
3. Copia el token inmediatamente — El valor del token sin procesar se muestra solo una vez. Cópialo antes de cerrar el diálogo.
4. Configura tu IdP — En la configuración SCIM de tu proveedor de identidad, ingresa la URL base y el token bearer.
5. Prueba la sincronización de usuarios — Activa una sincronización de prueba desde tu IdP y verifica que los usuarios aparezcan en el portal de Authagonal.

URL base de SCIM

Configura tu proveedor de identidad con la siguiente URL base:

https://{slug}.authagonal.io/scim/v2

Reemplaza {slug} con el slug de tu inquilino.

Página de configuración SCIM con generación de tokens

Gestión de tokens

Los tokens SCIM autentican las solicitudes de aprovisionamiento desde tu IdP. Puedes gestionar múltiples tokens por cliente:

Para revocar un token, haz clic en el botón Revocar junto a él. Los tokens revocados permanecen visibles en la lista con fines de auditoría pero dejan de aceptar solicitudes inmediatamente.

Gestión de tokens con indicadores de tokens activos y revocados

Probar la conectividad

Verifica que tu integración SCIM está funcionando consultando el endpoint ServiceProviderConfig:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

Una respuesta exitosa devuelve un documento JSON que describe las funcionalidades SCIM soportadas, incluyendo operaciones masivas, filtrado y capacidad de cambio de contraseña.

Scopes de OAuth

Los scopes permiten a los clientes solicitar porciones específicas de los datos o permisos de un usuario. Authagonal admite tanto los scopes estándar de OIDC como los scopes personalizados que definas para tus API.

Scopes integrados

Scopes personalizados

Define tus propios scopes en la página Scopes. Cada scope describe un permiso o recurso que un cliente puede solicitar (por ejemplo, billing.read, orders.write).

Claims personalizados en los tokens

Los claims personalizados tienen dos mitades. La fuente son los datos por usuario: cada AuthUser tiene un diccionario customAttributes que puedes poblar desde el Portal (Usuarios → usuario → Atributos personalizados), vía SCIM o mediante un hook de aprovisionamiento TCC. La liberación es por scope: la lista userClaims de cada scope nombra las claves que pueden salir del servidor.

Cuando un cliente solicita scopes, Authagonal recorre los scopes concedidos, une sus listas userClaims y emite solo esas claves de los customAttributes del usuario. Las claves desconocidas se descartan silenciosamente — un cliente no puede leer un atributo adivinando su nombre. Los claims OIDC estándar (sub, email, name, etc.) siguen la especificación y no están sujetos a la whitelist.

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted — it's not in the whitelist for any granted scope.
}

Asignar scopes a clientes

Añade los scopes permitidos en la pestaña Clientes → Scopes y Grants. Un cliente solo puede solicitar scopes que se le hayan concedido; los scopes desconocidos se rechazan con invalid_scope.

Marca

Personaliza la apariencia de las páginas de inicio de sesión de tu inquilino. La configuración de marca te permite hacer coincidir la experiencia de autenticación con la identidad visual de tu producto — desde logotipos y colores hasta personalizaciones avanzadas de CSS.

Apariencia

Configuración de apariencia con vista previa de color en vivo

Información de contacto

Controles de la página de inicio de sesión

Controla qué elementos aparecen en la página de inicio de sesión de tu inquilino:

Ejemplo de página de inicio de sesión con marca personalizada aplicada

CSS personalizado

Para un control total sobre la apariencia de la página de inicio de sesión, proporciona la URL de un archivo CSS en tus ajustes de marca. El archivo se carga después de los estilos por defecto, por lo que tus reglas tienen prioridad.

Modo oscuro

La app de inicio de sesión incluye temas claro, oscuro y del sistema. Los usuarios eligen desde un conmutador en la página de login; la elección se mantiene entre sesiones. Cuando está en system, la SPA sigue prefers-color-scheme en tiempo real.

Los valores claros se declaran en :root; las anulaciones oscuras están limitadas a .dark. El branding del tenant mediante customCssUrl siempre prevalece — tus colores se mantienen sin importar el tema del usuario.

Configuración

Configura las políticas de seguridad, webhooks y configuración del entorno a nivel de inquilino. Estas configuraciones se aplican globalmente a todos los clientes a menos que se anulen a nivel de cliente.

Política de contraseñas

Define los requisitos de complejidad de contraseña para todos los usuarios en tu inquilino:

Configuración de la política de contraseñas

Política de MFA

La política de MFA a nivel de inquilino establece el comportamiento predeterminado de autenticación multifactor. Los clientes individuales pueden anular esta configuración.

Sesión y bloqueo

Controla la duración de la sesión y el comportamiento de bloqueo de cuenta:

Configuración de sesión y bloqueo

Webhooks

Los webhooks te permiten reaccionar a eventos de autenticación en tiempo real. Dos eventos (onUserAuthenticated, onTokenIssued) son aplicables — por defecto se disparan de forma asíncrona y no bloquean al usuario, pero puedes activar la aplicación por evento para que una respuesta no 2xx o un cuerpo {"allow": false} rechace la acción. El resto de eventos son notificaciones — siempre fire-and-forget, nunca bloquean.

Configuraciones adicionales de webhooks:

Configuración de eventos de webhook

Verificar webhooks

Una vez configurada cualquier URL de webhook, Authagonal genera un secreto de firma por inquilino (un valor whsec_… que se muestra en modo de solo lectura en Ajustes → Webhooks). Cada entrega saliente lleva una cabecera X-Authagonal-Signature: t=<unix>,v1=<hex>, donde v1 es HMAC-SHA256(secret, "{t}.{body}") calculado sobre el cuerpo crudo de la solicitud. Vuelve a calcularlo en tu endpoint y compáralo en tiempo constante para confirmar que la solicitud realmente provino de Authagonal y no fue manipulada — y rechaza las entregas cuyo t sea demasiado antiguo para bloquear repeticiones.

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent — verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Ventana de mantenimiento

Establece una ventana de mantenimiento preferida para operaciones disruptivas como rotaciones de certificados y actualizaciones de infraestructura. Elige una hora UTC (0-23) — el portal también muestra la hora equivalente en tu zona horaria local para mayor comodidad.

Entorno sandbox

El entorno sandbox es un clon completo de tu inquilino de producción, disponible en una URL separada. Úsalo para probar cambios de configuración, integraciones SSO y endpoints de webhook sin afectar a los usuarios activos.

El sandbox es accesible en {slug}-sandbox.authagonal.io.

Controles del entorno sandbox

Facturación

Gestiona tu suscripción y facturación a través de la página de Facturación del portal. Esta página te ofrece un resumen de tu plan actual y proporciona acceso al portal de facturación de Stripe para gestionar métodos de pago, facturas y cambios de plan.

Información de suscripción

La página de facturación muestra los detalles de tu suscripción actual de un vistazo. Verás una insignia de estado indicando el estado de tu suscripción — active, trialing, past_due, canceled o unpaid — junto con el nombre de tu plan, el período de facturación actual (fechas de inicio y fin), y si tu suscripción está configurada para cancelarse al final del período actual.

Gestionar suscripción

Haz clic en el botón Gestionar suscripción para abrir el portal de facturación de Stripe en una nueva ventana. Desde ahí puedes actualizar tus métodos de pago, ver y descargar facturas, cambiar tu plan o cancelar tu suscripción.

Si aún no existe una suscripción, se muestra un botón de Configurar facturación en su lugar, que te guía a través de la selección de un plan y la introducción de datos de pago.

La página de facturación muestra los detalles de tu suscripción actual y proporciona acceso a Stripe

Dominios personalizados

Sirve tus páginas de autenticación desde tu propio dominio (por ejemplo, auth.tudominio.com) en lugar del predeterminado {slug}.authagonal.io. Los dominios personalizados brindan a tus usuarios una experiencia de autenticación fluida y con tu marca.

Añadir un dominio

Ingresa el nombre de host que deseas usar en el formulario de añadir dominio (por ejemplo, auth.tudominio.com). Una vez añadido, el dominio aparecerá en tu lista de dominios con un estado pending_verification.

Verificación DNS

Crea un registro CNAME apuntando tu dominio a {slug}.authagonal.io. Una vez que el registro DNS esté configurado, haz clic en Verificar para comprobar la propagación DNS.

auth.yourdomain.com.  CNAME  acme.authagonal.io.

Certificados TLS

Una vez que tu dominio esté verificado, necesitas un certificado TLS para que los usuarios puedan conectarse de forma segura a través de HTTPS. Authagonal soporta dos opciones:

Automático (cert-manager) — Authagonal aprovisiona y renueva certificados TLS automáticamente usando cert-manager. Esta es la opción recomendada para la mayoría de los usuarios. No se requiere configuración adicional.

Traer el propio (BYO) — Sube tu propio certificado y clave privada en formato PEM. Esta opción es útil si tu organización requiere certificados de una autoridad de certificación específica. Se hace seguimiento de la expiración del certificado para que puedas renovarlo antes de que caduque.

Estado del dominio

Cada dominio muestra una insignia de estado indicando su estado actual: pending_verification (DNS aún no confirmado), verified (DNS confirmado, TLS pendiente), active (totalmente operativo) o failed (problema de configuración detectado).

La lista de dominios muestra cada dominio personalizado y su estado actual

Sube tu propio certificado TLS y clave privada en formato PEM

Configuración de correo

Configura cómo tu tenant envía correos transaccionales — verificación, restablecimiento de contraseña y notificaciones MFA. Elige entre el remitente compartido predeterminado, un dominio personalizado verificado mediante Resend o tu propio servidor SMTP.

Proveedores de correo

Identidad del remitente

El correo y el nombre del remitente se comparten en todos los modos de proveedor. El correo del remitente es obligatorio; si el nombre está vacío, se usa el nombre del tenant.

Dominio personalizado de Resend

Verifica tu dominio de envío con Resend una sola vez y úsalo como dirección de remitente para este tenant. Los registros DNS TXT (SPF, DKIM) se proporcionan en la página de Dominios; Resend los valida automáticamente.

SMTP personalizado

Usa tu propio servidor SMTP — útil para relays internos, proveedores no cubiertos por Resend o fijación regulatoria.

Dominio de envío personalizado

Con el proveedor Resend puedes registrar tu propio dominio para que los correos provengan de tu marca (por ejemplo, noreply@acme.com) en lugar de @authagonal.io.

1. Ve a Ajustes → Correo y selecciona el proveedor Dominio personalizado de Resend.
2. Introduce tu nombre de dominio y haz clic en Registrar.
3. Añade los registros DNS mostrados (DKIM, SPF y return path) al DNS de tu dominio.
4. Haz clic en Comprobar verificación — cuando el DNS se propague (normalmente 1–10 minutos), el estado del dominio cambiará a verificado.

Pruebas

Usa el botón Enviar correo de prueba en Ajustes → Correo para verificar tu configuración. Se enviará un correo de prueba a tu dirección de administrador usando los ajustes guardados.

Registro de auditoría

El Registro de auditoría proporciona un registro de solo lectura de todas las acciones administrativas realizadas en tu inquilino. Cada cambio realizado a través del portal o la API se captura con contexto completo, dándote un rastro completo para cumplimiento y resolución de problemas.

Columnas del registro

Acciones registradas

Las siguientes acciones administrativas se registran en el registro de auditoría:

El registro de auditoría proporciona un registro completo de todas las acciones administrativas

Copias de seguridad

Authagonal realiza copias de seguridad automáticas de los datos de tu tenant cada hora. Las copias incluyen todos los usuarios, grupos, roles, clientes, conexiones SSO, tokens SCIM, marca y ajustes. Puedes ver el historial y descargar la última copia completa desde la página de Backups.

Cómo funcionan las copias

• Una copia completa se ejecuta una vez al día, capturando todas las tablas del shard de almacenamiento de tu tenant.
• Las copias incrementales se ejecutan cada hora, capturando solo las filas que cambiaron desde la última copia.
• Las copias se almacenan en Azure Blob Storage con la misma identidad administrada que usa tu tenant.
• Los registros eliminados se rastrean mediante tombstones y se incluyen en las copias para completitud de auditoría.

Descargar copias

Haz clic en "Descargar última" para obtener un archivo ZIP con la copia completa más reciente fusionada con todas las copias incrementales posteriores. Cada tabla se exporta como un archivo JSONL (un objeto JSON por línea).

Aplicaciones de aprovisionamiento

Las aplicaciones de aprovisionamiento reciben notificaciones webhook en tiempo real cuando se crean o autentican usuarios en tu inquilino. Esto permite que los sistemas descendentes configuren automáticamente cuentas, asignen licencias o sincronicen datos de usuario sin intervención manual.

Cómo funciona

Cuando ocurre un evento de usuario (creación o autenticación), Authagonal llama a la URL de callback de tu aplicación de aprovisionamiento usando el patrón TCC (Try/Confirm/Cancel). Este enfoque de tres fases asegura un aprovisionamiento fiable a través de múltiples sistemas descendentes:

Carga del webhook

Cada solicitud de webhook incluye una carga JSON con los siguientes campos:

Añadir una aplicación de aprovisionamiento

Para añadir una aplicación de aprovisionamiento, proporciona un nombre, una URL de callback y una clave API opcional. La clave API se envía como token Bearer en el encabezado Authorization de cada solicitud de webhook, permitiendo que tu aplicación autentique las solicitudes de Authagonal.

Pruebas

Haz clic en Probar junto a cualquier aplicación de aprovisionamiento para enviar una solicitud de prueba a tu URL de callback. Los resultados de la prueba muestran el código de estado HTTP y el cuerpo de la respuesta, ayudándote a verificar que tu aplicación está recibiendo y procesando webhooks correctamente.

Prueba las aplicaciones de aprovisionamiento para verificar la entrega y manejo de respuestas del webhook

Límites del plan

El número máximo de aplicaciones de aprovisionamiento es configurable por inquilino, con un límite predeterminado de 6. Este límite puede ser ajustado por un administrador si tu flujo de trabajo requiere objetivos de aprovisionamiento adicionales.

Equipo

La página de Equipo gestiona los administradores del portal — las personas que pueden acceder y configurar tu inquilino a través del portal de gestión. Todos los miembros del equipo tienen acceso administrativo completo a todos los aspectos de la configuración de tu inquilino.

Lista de administradores

La lista de administradores muestra el nombre, dirección de correo electrónico y la fecha en que fue añadido cada miembro del equipo. Un indicador "Tú" se muestra junto a la fila del usuario actual para que puedas identificar fácilmente tu propia cuenta.

Invitar administradores

Para invitar a un nuevo miembro del equipo, proporciona su dirección de correo electrónico, nombre y una contraseña temporal (mínimo 8 caracteres). El usuario invitado inicia sesión con la contraseña temporal y debe cambiarla en el primer inicio de sesión.

Campos de invitación

Las invitaciones de administrador crean un usuario totalmente aprovisionado — sin viaje de ida y vuelta por correo.

Eliminar administradores

Haz clic en Eliminar junto a cualquier miembro del equipo para revocar su acceso. Se muestra un diálogo de confirmación antes de que la eliminación se finalice. No puedes eliminarte a ti mismo — siempre debe haber al menos un administrador en el equipo.

Gestiona los administradores del portal desde la página de Equipo

Importar y migrar

Migra un sistema de identidad existente a tu tenant de Authagonal. Se admiten dos fuentes — Duende IdentityServer (una base de datos SQL Server) y Auth0 (la Management API). Cada una ejecuta una vista previa de solo lectura para que revises exactamente qué se copiará antes de confirmar.

Importación desde Duende IdentityServer

Migra clientes, scopes, usuarios y roles desde una base de datos SQL Server de Duende IdentityServer existente a tu tenant de Authagonal. La importación se ejecuta en dos fases — vista previa y commit — para que puedas revisar lo que se copiará antes de realizar cualquier cambio.

Qué se importa

El importador lee de la ConfigurationDb de Duende y de las tablas de ASP.NET Identity y escribe las filas mapeadas en tu tenant. Se omiten artefactos de corta duración como persisted grants, device codes y claves de firma.

Vista previa antes del commit

Pega tu cadena de conexión a ConfigurationDb / IdentityDb de Duende y haz clic en Ejecutar vista previa. La vista previa abre una conexión de solo lectura y cuenta cada fila que se importaría — no se escribe nada.

• Recuentos por entidad de clientes, scopes, usuarios, roles y asignaciones de roles.
• Colisiones de propietario: administradores del tenant cuyo <code>userId</code> existente difiere del <code>sub</code> entrante de Duende.
• Avisos de tablas desconocidas y columnas no mapeadas para que sepas qué se descartará.

Panel de vista previa con recuentos, colisiones y avisos

Hashes de contraseña

Duende almacena contraseñas con ASP.NET Identity V3 (PBKDF2). El PasswordHasher de Authagonal verifica ese formato directamente y rehashea al formato nativo en el primer inicio de sesión exitoso — los usuarios conservan su contraseña sin flujo de restablecimiento.

Rotación de userId del propietario

Si el correo de un administrador del tenant coincide con un usuario en la base de datos de Duende, el userId del admin en Authagonal se rota para coincidir con el sub de Duende. Esto mantiene tokens y entradas de auditoría consistentes tras la migración. La vista previa lista cada colisión antes del commit.

Ejecutar la importación

Haz clic en Iniciar importación tras revisar la vista previa. La fase de commit escribe clientes, scopes, usuarios, roles y referencias de inicio de sesión externo en los stores del tenant. Las filas duplicadas de clientId, scope name, email y role name se omiten — el importador es seguro de re-ejecutar.

Qué no se importa

• Persisted grants, device codes, server-side sessions — de corta duración, se regeneran automáticamente.
• Claves de firma — Authagonal emite sus propias claves por tenant.
• Columnas y tablas personalizadas — cualquier cosa fuera del esquema estándar de Duende se emite como aviso para que sepas que los datos se descartaron.
• Clientes deshabilitados — se importan deshabilitados; reactívalos desde la página Clientes cuando estés listo.

Importar desde Auth0

Conecta Authagonal con la Management API de tu tenant de Auth0 y trae tus aplicaciones, APIs, roles, usuarios y conexiones empresariales. Los IDs de usuario y aplicación importados se conservan, de modo que las referencias existentes a sub y client_id siguen resolviéndose tras el cambio.

Qué necesitarás

Crea una aplicación Machine-to-Machine en Auth0 autorizada para la Management API, con estos scopes de lectura: read:users, read:clients, read:resource_servers, read:roles, read:connections, read:client_grants. Pega su dominio, client ID y client secret en el formulario de importación — solo se usan para la importación.

Qué se importa

Contraseñas

La Management API de Auth0 nunca devuelve los hashes de contraseña. Si dispones de la exportación masiva de contraseñas asistida por soporte de Auth0 (NDJSON), proporciónala — los hashes bcrypt se importan tal cual y tus usuarios conservan sus contraseñas sin restablecimiento. Ese archivo también incluye el conjunto completo de usuarios, eliminando el límite de 1.000 usuarios del listado de la API de Auth0. Sin él, los usuarios se importan como perfiles y establecen una nueva contraseña en el primer inicio de sesión.

Referencia de API

Cada inquilino expone un servidor OIDC compatible con estándares en https://{slug}.authagonal.io. Todos los endpoints siguen las especificaciones OAuth 2.0 y OpenID Connect. Esta referencia cubre todos los endpoints con los que tu aplicación puede necesitar interactuar.

Flujo de código de autorización con PKCE

Descubrimiento OIDC y JWKS

El documento de descubrimiento permite que las bibliotecas de cliente OIDC se configuren automáticamente. No se requiere autenticación para ninguno de los endpoints.

GET /.well-known/openid-configuration

Devuelve el documento de configuración del proveedor OpenID. La respuesta incluye todos los metadatos que tu cliente necesita para interactuar con este inquilino.

GET /.well-known/openid-configuration/jwks

Devuelve el JSON Web Key Set utilizado para verificar las firmas de tokens. La respuesta contiene un array keys con claves públicas RSA, cada una incluyendo los campos kty, use, kid, alg, n y e.

curl https://acme.authagonal.io/.well-known/openid-configuration

Endpoint de autorización

GET /connect/authorize

Inicia un flujo de código de autorización. El usuario debe tener una sesión activa o será redirigido a la página de inicio de sesión. En caso de éxito, el usuario es redirigido de vuelta a tu aplicación con un código de autorización.

Respuesta exitosa: Redirección 302 a redirect_uri con los parámetros de consulta code y state.

Respuesta de error: Redirección 302 con los parámetros de consulta error, error_description y state.

Pushed Authorization Requests (PAR)

RFC 9126. En lugar de poner cada parámetro de autorización en la URL, tu cliente los envía por POST a /connect/par con autenticación normal y recibe una request_uri opaca y de corta duración. El navegador visita luego /connect/authorize?client_id=...&request_uri=... — nada más queda en el historial del navegador, los logs del servidor ni los encabezados Referer, y el servidor ya ha verificado la integridad de los parámetros bajo autenticación de cliente.

POST /connect/par

La autenticación de cliente es la misma que en /connect/token: HTTP Basic con client_id/client_secret o credenciales codificadas en el formulario. Los clientes públicos publican sin secreto. El cuerpo lleva los mismos parámetros que enviarías normalmente a /connect/authorize; request_uri en sí es rechazado (encadenar un PAR está prohibido por §2.1 de la especificación). Devuelve 201 Created.

Respuesta

En la llamada posterior GET /connect/authorize?client_id=…&request_uri=…, todos los demás parámetros se toman de la carga útil enviada y cualquier parámetro de consulta extra se ignora. El client_id en la llamada de autorización debe coincidir con el cliente que envió la solicitud. Una vez consumida (o cuando transcurre expires_in), la request_uri se elimina del almacén.

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

Endpoint de token

POST /connect/token

Intercambia credenciales por tokens. Las solicitudes deben usar Content-Type: application/x-www-form-urlencoded. La autenticación del cliente puede proporcionarse a través de HTTP Basic auth (Authorization: Basic base64(client_id:client_secret)) o como parámetros del cuerpo del formulario (client_id + client_secret).

Concesión de código de autorización

Concesión de token de actualización

Concesión de credenciales de cliente

Concesión de código de dispositivo

Respuesta del token:

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Endpoint UserInfo

GET /connect/userinfo

Devuelve claims sobre el usuario autenticado. Requiere un token de acceso válido con el alcance openid.

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Introspección de token (RFC 7662)

POST /connect/introspect

Valida un token y devuelve sus metadatos. Requiere credenciales de cliente (autenticación Basic o parámetros del cuerpo del formulario).

Respuesta de token activo:

Respuesta de token inactivo: { "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

Revocación de token (RFC 7009)

POST /connect/revocation

Revoca un token emitido previamente. Requiere credenciales de cliente.

El endpoint siempre devuelve 200 OK, incluso para tokens inválidos o ya revocados, según la especificación RFC 7009.

Autorización de dispositivo (RFC 8628)

POST /connect/deviceauthorization

Inicia el flujo de autorización de dispositivo para dispositivos con restricciones de entrada (CLIs, smart TVs, dispositivos IoT). El dispositivo muestra un código al usuario, quien luego aprueba la solicitud en un dispositivo separado con navegador.

Respuesta:

Flujo de aprobación: El usuario visita la verification_uri, ingresa el user_code y aprueba la solicitud. Mientras tanto, el dispositivo consulta periódicamente el endpoint de token con el device_code.

Códigos de error de consulta periódica:

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

Cierre de sesión / Logout

GET POST /connect/endsession

Cierra la sesión del usuario actual, activa el cierre de sesión por canal trasero a todos los clientes con un BackChannelLogoutUri registrado, y revoca todas las concesiones.

Si se proporciona un post_logout_redirect_uri válido que coincida con una URI registrada, el usuario recibe una redirección 302. De lo contrario, una respuesta JSON confirma que la sesión ha sido finalizada.

Referencia de API SCIM 2.0

Authagonal soporta el protocolo SCIM 2.0 para el aprovisionamiento automatizado de usuarios y grupos. Los proveedores de identidad como Okta, Azure AD y OneLogin pueden usar esta API para mantener tu inquilino de Authagonal sincronizado con tu directorio corporativo.

URL base: https://{slug}.authagonal.io/scim/v2

Autenticación: Todas las solicitudes requieren un token Bearer. Genera un token SCIM en el portal bajo Settings > SCIM Provisioning.

Encabezados comunes:

Los endpoints de lista soportan paginación a través de los parámetros de consulta startIndex (basado en 1) y count (máx. 200), y filtrado a través del parámetro filter (por ejemplo, userName eq "user@example.com").

Usuarios

GET /scim/v2/Users — Lista usuarios con paginación y filtrado opcionales.

GET /scim/v2/Users/{id} — Obtiene un usuario individual por su ID de usuario de Authagonal.

POST /scim/v2/Users — Crea un nuevo usuario. Devuelve 201 Created.

PUT /scim/v2/Users/{id} — Reemplazo completo de un recurso de usuario. Todos los campos deben proporcionarse.

PATCH /scim/v2/Users/{id} — Actualización parcial usando SCIM PatchOp.

DELETE /scim/v2/Users/{id} — Eliminación suave del usuario (desactiva la cuenta y revoca todos los tokens). Devuelve 204 No Content.

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@acme.com",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

Grupos

GET /scim/v2/Groups — Lista todos los grupos con paginación y filtrado opcionales.

GET /scim/v2/Groups/{id} — Obtiene un grupo individual por ID, incluyendo su lista de miembros.

POST /scim/v2/Groups — Crea un nuevo grupo. Devuelve 201 Created.

PUT /scim/v2/Groups/{id} — Reemplazo completo de un recurso de grupo (incluyendo su lista de miembros).

PATCH /scim/v2/Groups/{id} — Actualización parcial para añadir o eliminar miembros del grupo.

DELETE /scim/v2/Groups/{id} — Eliminación permanente del grupo. Devuelve 204 No Content.

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

API del portal (automatización)

La API del portal permite que tu propio backend automatice todo lo que puedes hacer en el portal — gestionar usuarios, clientes, grupos, roles, ámbitos, conexiones SSO y configuración — usando una credencial de máquina a máquina. Es la misma API que llama la interfaz del portal.

URL base: https://portal-api.<your-domain>/api/v1. Las solicitudes se autentican con un token de acceso Bearer; el inquilino se toma del token, no de la URL.

Crear una credencial de API

En el portal, abre Clients → Create API credential, elige un nivel de acceso y dale un nombre. Authagonal genera un cliente OAuth client_credentials configurado para la API del portal y devuelve un ID de cliente y un secreto.

Niveles de acceso

Obtener un token

Intercambia la credencial por un token de acceso en el endpoint de token de tu inquilino de administración — https://<your-tenant>.<your-domain>/connect/token — y luego envía el token como un encabezado Bearer a la API del portal. Los tokens son válidos durante una hora.

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoints

Todas las rutas son relativas a la URL base y requieren un token de acceso Bearer. El ámbito junto a cada grupo es el nivel de acceso mínimo que necesitan las credenciales. Los endpoints de listado aceptan los parámetros de consulta startIndex y count.

GET/api/v1/clients— Listar clientes OAuth.

GET/api/v1/clients/{id}— Obtener un cliente por su ID.

POST/api/v1/clients— Crear un cliente. Devuelve el ID del cliente y, para clientes confidenciales, un secreto de un solo uso.

PUT/api/v1/clients/{id}— Actualizar un cliente (URIs de redirección, tipos de concesión, duración de tokens, requisitos PKCE/PAR).

DELETE/api/v1/clients/{id}— Eliminar un cliente.

POST/api/v1/clients/api-credential— Generar una credencial de API del Portal de máquina a máquina.

GET/api/v1/users— Listar usuarios. Admite startIndex, count y search (prefijo de correo / nombre).

GET/api/v1/users/count— Número total de usuarios del inquilino.

GET/api/v1/users/stats/mfa— Estadísticas de inscripción en MFA.

GET/api/v1/users/{id}— Obtener un usuario.

POST/api/v1/users— Crear un usuario con correo y contraseña.

PUT/api/v1/users/{id}— Actualizar un usuario (perfil, correo, estado habilitado/bloqueado).

DELETE/api/v1/users/{id}— Eliminar un usuario.

GET/api/v1/users/{id}/mfa— Get a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfa— Reset a user's MFA enrollment.

GET/api/v1/roles— Listar roles.

POST/api/v1/roles— Crear un rol.

DELETE/api/v1/roles/{id}— Eliminar un rol.

POST/api/v1/roles/assign— Asignar un rol a un usuario.

POST/api/v1/roles/unassign— Quitar un rol de un usuario.

GET/api/v1/groups— Listar grupos.

GET/api/v1/groups/{id}— Obtener un grupo con sus miembros.

POST/api/v1/groups— Crear un grupo.

POST/api/v1/groups/{id}/members— Agregar miembros a un grupo.

DELETE/api/v1/groups/{groupId}/members/{userId}— Eliminar un miembro de un grupo.

DELETE/api/v1/groups/{id}— Eliminar un grupo.

GET/api/v1/group-role-mappings— Listar las asignaciones de grupo a rol (roles concedidos al emitir el token según la pertenencia al grupo).

GET/api/v1/scopes— Listar ámbitos de API.

POST/api/v1/scopes— Crear un ámbito.

DELETE/api/v1/scopes/{name}— Eliminar un ámbito.

GET/api/v1/saml/connections— Listar conexiones SAML.

POST/api/v1/saml/connections— Crear una conexión SAML.

DELETE/api/v1/saml/connections/{id}— Eliminar una conexión SAML.

GET/api/v1/oidc/connections— Listar conexiones OIDC.

POST/api/v1/oidc/connections— Crear una conexión OIDC.

DELETE/api/v1/oidc/connections/{id}— Eliminar una conexión OIDC.

GET/api/v1/sso/domains— Listar los dominios enrutados a conexiones SSO (descubrimiento de dominio de origen).

GET/api/v1/branding— Obtener la personalización del inquilino (colores, logotipo, idiomas admitidos).

PUT/api/v1/branding— Actualizar la personalización del inquilino.

GET/api/v1/settings— Obtener la configuración del inquilino (webhooks, registro público, política de tokens).

PUT/api/v1/settings— Actualizar la configuración del inquilino.

POST/api/v1/settings/webhook-secret/regenerate— Rotar el secreto de firma del webhook.

POST/api/v1/settings/test-email— Enviar un correo de prueba con la configuración de correo actual.

GET/api/v1/custom-domains— Listar los dominios de inicio de sesión personalizados y su estado de verificación.

POST/api/v1/custom-domains— Agregar un dominio personalizado.

POST/api/v1/custom-domains/{domain}/verify— Iniciar la verificación DNS de un dominio personalizado.

DELETE/api/v1/custom-domains/{domain}— Eliminar un dominio personalizado.

GET/api/v1/email/domains— Listar los dominios de correo del remitente.

GET/api/v1/audit— Consultar el registro de auditoría del inquilino.

Ejemplo: crear un usuario

curl -X POST https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@acme.com",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "ada@acme.com" }

Flujos de autenticación

Los flujos de autenticación cubren cómo los usuarios finales interactúan con tu inquilino de Authagonal — iniciar sesión, registrarse, restablecer contraseñas y configurar MFA. Estos endpoints son utilizados por la página de inicio de sesión alojada y pueden llamarse directamente si estás construyendo una interfaz de inicio de sesión personalizada.

Inicio de sesión

POST /api/auth/login

Autentica a un usuario con correo electrónico y contraseña. En caso de éxito, firma una cookie de sesión y devuelve el perfil del usuario. Si MFA está configurado, la respuesta indica que se requiere un segundo factor antes de que la sesión esté completamente establecida.

Cuerpo de la solicitud:

{
  "email": "user@example.com",
  "password": "correct-horse-battery-staple"
}

Respuesta exitosa:

Respuesta de MFA requerido: Cuando el usuario tiene MFA inscrito, la respuesta incluye mfaRequired: true junto con un challengeId y un array methods que lista los métodos MFA disponibles.

Respuesta de configuración de MFA requerida: Cuando el inquilino requiere MFA pero el usuario aún no se ha inscrito, la respuesta incluye mfaSetupRequired: true con un setupToken para el flujo de inscripción.

Respuestas de error:

Verificación SSO: Si el dominio de correo electrónico del usuario tiene una conexión SSO configurada, el endpoint de inicio de sesión devuelve sso_required con un redirectUrl. El cliente debe redirigir al usuario al proveedor SSO.

Bloqueo de cuenta: Después de maxFailedAttempts intentos consecutivos de inicio de sesión fallidos, la cuenta se bloquea durante lockoutDurationMinutes. Ambos valores son configurables en la configuración del inquilino.

Registro

POST /api/auth/register

Crea una nueva cuenta de usuario. Se envía un correo electrónico de verificación automáticamente — el usuario debe verificar su correo electrónico antes de poder iniciar sesión.

Cuerpo de la solicitud:

{
  "email": "newuser@example.com",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

Éxito: 201 Created con el userId de la nueva cuenta.

Respuestas de error:

Restablecimiento de contraseña

POST /api/auth/forgot-password

Solicita un correo electrónico de restablecimiento de contraseña. El endpoint siempre devuelve una respuesta exitosa independientemente de si el correo electrónico existe, para prevenir la enumeración de correos electrónicos.

{
  "email": "user@example.com"
}

POST /api/auth/reset-password

Restablece la contraseña del usuario usando el token del enlace del correo electrónico.

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

Efectos secundarios de un restablecimiento de contraseña exitoso:

• El contador de intentos de inicio de sesión fallidos se reinicia a cero
• Todos los tokens de actualización existentes son revocados
• Se genera un nuevo sello de seguridad (invalidando todas las sesiones existentes)

Configuración y verificación de MFA

Authagonal soporta tres métodos MFA: TOTP (aplicaciones autenticadoras), WebAuthn (llaves de seguridad y biometría) y códigos de recuperación de un solo uso.

Configuración TOTP

POST /api/auth/mfa/totp/setup — Devuelve un URI de datos de código QR y una clave de entrada manual. El usuario escanea el código QR con su aplicación autenticadora (Google Authenticator, Authy, 1Password, etc.) y luego confirma la inscripción.

POST /api/auth/mfa/totp/confirm — Confirma la inscripción TOTP validando un código de 6 dígitos de la aplicación autenticadora.

{
  "code": "123456"
}

Configuración WebAuthn

POST /api/auth/mfa/webauthn/setup — Devuelve opciones de creación de credenciales para la API WebAuthn. El navegador llama a navigator.credentials.create() con estas opciones.

POST /api/auth/mfa/webauthn/confirm — Confirma la inscripción WebAuthn enviando la respuesta de atestación del navegador.

Códigos de recuperación

POST /api/auth/mfa/recovery/generate — Genera 10 códigos de recuperación de un solo uso de 8 caracteres. Cada código puede usarse exactamente una vez para omitir MFA.

Verificación MFA

POST /api/auth/mfa/verify — Completa el desafío MFA después de un inicio de sesión exitoso con contraseña.

Estado de MFA

GET /api/auth/mfa/status — Devuelve los métodos MFA actualmente inscritos del usuario.

Flujo de inicio de sesión SSO

Authagonal soporta tanto conexiones SSO basadas en SAML 2.0 como en OIDC. El enrutamiento basado en dominio detecta automáticamente qué proveedor SSO usar según la dirección de correo electrónico del usuario.

Verificación SSO

GET /api/auth/sso-check?email=user@acme.com

Flujo SAML

El usuario es redirigido a GET /saml/{connectionId}/login que envía una AuthnRequest SAML al proveedor de identidad. El IdP autentica al usuario y publica una respuesta SAML de vuelta al endpoint del Assertion Consumer Service (ACS). Authagonal valida la aserción, crea o actualiza al usuario y firma una cookie de sesión.

Los metadatos SAML para configurar tu IdP están disponibles en GET /saml/{connectionId}/metadata.

Flujo OIDC

El usuario es redirigido a GET /oidc/{connectionId}/login que redirige al proveedor de identidad ascendente con PKCE. Después de que el usuario se autentica, el callback en /oidc/callback intercambia el código de autorización, valida el token de ID y crea o actualiza al usuario.

Aprovisionamiento JIT: Tanto los flujos SAML como OIDC soportan aprovisionamiento just-in-time. Si el usuario no existe ya en el inquilino, se crea automáticamente a partir de los claims del proveedor de identidad. Si ya existe, sus atributos de perfil se actualizan para coincidir con los valores más recientes del proveedor.

Crea una interfaz de inicio de sesión personalizada

Reemplaza las pantallas alojadas de inicio de sesión, registro, restablecimiento de contraseña y MFA de Authagonal por tu propia interfaz, mientras Authagonal sigue encargándose de la autenticación, MFA, SSO, sesiones y emisión de tokens. Dos vías: usar nuestra biblioteca de componentes de React, o llamar a la API de autenticación directamente desde cualquier framework. Es opcional — primero habilita Custom login UI en la configuración del inquilino.

Requisito previo: un dominio personalizado en tu raíz

La sesión de inicio de sesión es una cookie de origen propio (first-party), por lo que tu interfaz y el servidor de autenticación de Authagonal deben compartir un dominio registrable. Apunta un dominio de autenticación personalizado a Authagonal en la misma raíz donde se ejecuta tu app — p. ej. autenticación en login.acme.com, app en app.acme.com. La configuración Custom login UI permanece deshabilitada hasta que exista un dominio personalizado activo.

Agrega también el origen de tu interfaz (p. ej. https://app.acme.com) a los Allowed CORS origins de tu cliente OAuth — la misma lista que configuras para el intercambio de tokens.

React: @authagonal/login

npm i @authagonal/login incluye la lógica de autenticación y la interfaz en un solo paquete — el mismo sobre el que está construido el inicio de sesión alojado de Authagonal. Elige tu nivel:

• App completa — incorpora App y aplícale tu tema mediante la marca.
• Componer páginas — usa LoginPage, MfaChallengePage, ResetPasswordPage… dentro de tu propio diseño.
• Primitivas + lógica — crea tus propias pantallas con AuthLayout/Button/Input y el cliente de la API (login, mfaVerify, forgotPassword, …).

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

function MyLogin() {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login({ email, password });        // POST /login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step → mfaVerify(...) */}
      else window.location.href = res.returnUrl;            // hand off to /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

Cualquier framework: llama a la API de autenticación

¿No usas React? Llama directamente a los endpoints del flujo de autenticación (bajo /api/auth) y luego entrega al flujo OIDC estándar /connect/authorize. Envía credentials: 'include' para que se almacene la cookie de sesión.

# 1. Authenticate (browser fetch — credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"jane@acme.com","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow — top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

Planes y límites

Authagonal ofrece cuatro niveles de plan. Todos los planes incluyen todas las funcionalidades — la única diferencia es el límite de Usuarios Activos Mensuales (MAU) y el precio de excedentes.

Niveles de plan

Usuarios Activos Mensuales (MAU)

Un Usuario Activo Mensual es cualquier usuario único que se autentica exitosamente al menos una vez durante un mes de facturación. Los usuarios aprovisionados a través de SCIM pero que no han iniciado sesión no cuentan para tu total de MAU.

Excedentes — Si tu plan admite excedentes, los usuarios más allá del límite de MAU se facturan a la tarifa por usuario mostrada en la tabla de planes anterior. Puedes establecer un tope de excedente para limitar tu gasto máximo durante el período de facturación.

Aplicación — Si tu plan no admite excedentes (Starter), los usuarios más allá del límite de MAU no pueden iniciar sesión hasta el próximo período de facturación o hasta que actualices a un plan que admita excedentes.