Crear un enlace de Admin Portal

POST /v1/admin-portal-links · permiso admin-portal-links:write

Crea un enlace que permite al administrador de TI de una de tus organizaciones clientes configurar SSO, la sincronización de directorios, la verificación de dominios y más en el Admin Portal alojado, sin pasar por tu equipo de soporte. Genera un enlace nuevo cada vez que tu administrador haga clic en «Configurar SSO» en tu aplicación y redirígelo a url de inmediato: el enlace es válido durante 5 minutos y abre una única sesión del portal, una sola vez. url solo se devuelve en esta respuesta, una vez; ningún endpoint la devuelve después. La respuesta incluye Cache-Control: no-store, y una respuesta reenviada para el mismo Idempotency-Key omite url e incluye secret_redacted: true. La sesión del portal dura 60 minutos de inactividad, con un máximo de 8 horas; revócala con DELETE /v1/admin-portal-links/{link_id}. La creación se audita como admin_portal_link.created (la URL nunca entra en el registro de auditoría).

audit_logs requiere el plan Business y log_streams el plan Enterprise; las demás intenciones están disponibles en todos los planes. delivery: email envía una invitación en su lugar: dura 7 días y se envía por correo a recipient_email; la respuesta no incluye url ni dirección. Cuando el destinatario la abre, se envía un código de 6 dígitos (válido 10 minutos) a la misma dirección, y solo el código verificado abre la sesión del portal. Si no se puede enviar el correo de invitación, la llamada responde 503 service_unavailable con Retry-After y no crea nada. Revoca una invitación con DELETE /v1/admin-portal-links/{link_id}. La dirección del destinatario nunca aparece en una respuesta, una lista, el registro de auditoría ni un log.

Solicitud

Campo Tipo Obligatorio Descripción
organization_id string sí ID de la organización (org_…); debe existir en este entorno.
intents string[] sí De 1 a 6 valores de sso, dsync, domain_verification, certificate_renewal, audit_logs (Business), log_streams (Enterprise), sin repetir ninguno.
return_url string sí URL absoluta https de como máximo 2048 bytes, sin información de usuario ni fragmento. Su origen debe ser el origen de un redirect_uri de una aplicación activa registrada en este entorno.
delivery string no link (predeterminado; url de un solo uso válida 5 minutos en la respuesta) o email (invitación válida 7 días enviada por correo a recipient_email; sin url).
recipient_email string no Solo con delivery: email, y obligatorio en ese caso; como máximo 320 caracteres. Si falta: 422 /recipient_email required; con delivery: link: not_allowed; dirección no válida: invalid_value.

Respuesta

201 Created con el enlace y su url de un solo uso.

{
  "id": "apl_01j9xv2c4d6e8f0g2h4j6k8m0n",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "intents": [
    "dsync",
    "sso"
  ],
  "delivery": "link",
  "return_url": "https://app.example.com/settings/sso",
  "expires_at": "2026-10-12T09:36:00.123456Z",
  "consumed_at": null,
  "revoked_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z",
  "url": "https://acme.eu.keenauth.app/portal/l/<token>"
}

Errores

HTTP code Cuándo
403 plan_feature_unavailable Una intención necesita un plan superior; feature y required_plan lo indican.
404 not_found La organización no existe en este entorno.
409 organization_disabled La organización no está activa (deshabilitada); no se crea ningún enlace.
409 organization_pending_deletion La organización está programada para eliminación; no se crea ningún enlace.
422 validation_failed Falta un campo o no es válido; /return_url origin_not_registered cuando su origen no es el de una aplicación registrada; /recipient_email required, not_allowed o invalid_value.
401 unauthenticated La credencial falta, no es válida o fue revocada.
403 insufficient_permissions La credencial no tiene el permiso necesario.
429 rate_limited Se superó el límite de frecuencia; reintenta después del periodo Retry-After.
503 service_unavailable Una dependencia no está disponible temporalmente, o (delivery: email) no se puede enviar el correo de invitación; no se crea nada. Reintenta después del periodo Retry-After.

Ejemplo

curl -i -X POST "https://api.eu.keenauth.com/v1/admin-portal-links" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","intents":["sso","dsync"],"return_url":"https://app.example.com/settings/sso"}'

Enviar una invitación por correo

curl -i -X POST "https://api.eu.keenauth.com/v1/admin-portal-links" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","intents":["sso"],"return_url":"https://app.example.com/settings/sso","delivery":"email","recipient_email":"it@customer.example"}'

201 Created; la respuesta no incluye url ni dirección:

{
  "id": "apl_01j9xv2c4d6e8f0g2h4j6k8m0n",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "intents": [
    "sso"
  ],
  "delivery": "email",
  "return_url": "https://app.example.com/settings/sso",
  "expires_at": "2026-10-19T09:31:00.123456Z",
  "consumed_at": null,
  "revoked_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z"
}

Con la CLI: keenauth admin-portal-links create --organization-id org_01j9xk3m7q8r2s4t6v8w0y2z4a --intents sso --return-url https://app.example.com/settings/sso --delivery email --recipient-email it@customer.example.