Passkeys y Aprobaciones

Koywe expone una capa pública de aprobación para acciones sensibles. Combina passkeys WebAuthn, tokens MFA de corta duración y aprobaciones por política transaccional.

Familias de Endpoints Públicos

WebAuthn / Passkeys

POST /api/v1/organizations/{organizationId}/webauthn/register/init
POST /api/v1/organizations/{organizationId}/webauthn/register/complete
POST /api/v1/organizations/{organizationId}/webauthn/challenge
POST /api/v1/organizations/{organizationId}/webauthn/verify
GET /api/v1/organizations/{organizationId}/webauthn/credentials
GET /api/v1/organizations/{organizationId}/webauthn/credentials/all

Política Transaccional y Aprobaciones

POST /api/v1/organizations/{organizationId}/policy
GET /api/v1/organizations/{organizationId}/policy
POST /api/v1/organizations/{organizationId}/policy/rules
GET /api/v1/organizations/{organizationId}/policy/approvals
POST /api/v1/organizations/{organizationId}/policy/approvals/{approvalId}/approve
POST /api/v1/organizations/{organizationId}/policy/approvals/{approvalId}/reject

Enrollment de Passkeys para Usuarios Humanos

Los usuarios humanos deben enrollar sus passkeys en Koywe Platform, no llamando directamente los endpoints de WebAuthn.

Este es el flujo recomendado para super admins y operadores que necesitan aprobar acciones sensibles:

Inicia sesión en Koywe Platform con tu usuario normal.
Si tu organización todavía no tiene passkeys activadas, Koywe mostrará un mensaje para enrollar o activar passkeys para la organización.
Un super admin inicia el flujo y aprueba la activación de passkeys para la organización.
Después, cada usuario que deba operar flujos protegidos verá un prompt para crear su propia passkey.
Una vez creada, ese usuario podrá usar la passkey para MFA y aprobaciones dentro de la plataforma.

Cómo se Ve la Experiencia

Los usuarios verán un prompt dentro de la plataforma para crear una passkey cuando la organización lo requiera.
El navegador o dispositivo abrirá el diálogo nativo de passkeys.
El usuario puede guardar la passkey en el dispositivo actual o en un password manager / cloud keychain.
Si su proveedor sincroniza passkeys entre dispositivos, normalmente la passkey quedará disponible automáticamente en otros dispositivos enrolados.

Guía Operativa Recomendada

Pide a por lo menos un super admin que complete primero la activación de la organización.
Pide a cada aprobador que enrolle su propia passkey antes de habilitar políticas de aprobación más estrictas.
Recomienda guardar la passkey en un proveedor con sincronización, para no depender de un solo dispositivo.
Trata este como el flujo estándar para usuarios humanos; reserva el flujo de firma para API users de abajo para operaciones delegadas o de servicio.

Tutorial de Firma para API Users

Si quieres que un API user participe en flujos de MFA delegado o firma de embedded wallet, la forma más simple de configurarlo es:

generar un par de llaves PEM
enviar la llave pública para enrollment
hacer que un usuario root apruebe el enrollment
firmar payloads protegidos localmente con la llave privada

Paso 0: Crear las Credenciales del API User

Antes de enrollar MFA delegado, crea las credenciales API del usuario. Consulta Configuración de Organización e Invitaciones.

Paso 1: Generar el Par de Llaves PEM


openssl genpkey -algorithm RSA -out api-user-private.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in api-user-private.pem -out api-user-public.pem

Guarda la llave privada en tu secret manager. Solo la llave pública debe enviarse a Koywe.

Paso 2: Enviar la Llave Pública para MFA Delegado


curl -X POST 'https://api-sandbox.koywe.com/api/v1/auth/organizations/TU_ORG_ID/api-users/mfa/prepare' \
  -H 'Authorization: Bearer TU_TOKEN_DEL_API_USER' \
  -H 'Content-Type: application/json' \
  -d '{
    "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
  }'

Esto crea una aprobación pendiente y entrega el pendingApprovalId.

Paso 3: El Usuario Root Aprueba el Enrollment

El usuario root carga la solicitud preparada:


curl -X POST 'https://api-sandbox.koywe.com/api/v1/auth/organizations/TU_ORG_ID/api-users/mfa/enroll/prepare' \
  -H 'Authorization: Bearer TU_TOKEN_ROOT' \
  -H 'Content-Type: application/json' \
  -d '{
    "pendingApprovalId": "pap_123"
  }'

Luego firma la solicitud retornada con su passkey y finaliza con:


curl -X POST 'https://api-sandbox.koywe.com/api/v1/auth/organizations/TU_ORG_ID/api-users/mfa/enroll/approve' \
  -H 'Authorization: Bearer TU_TOKEN_ROOT' \
  -H 'Content-Type: application/json' \
  -d '{
    "pendingApprovalId": "pap_123",
    "stampedRequest": { "...": "firmado-por-passkey-root" }
  }'

Puedes verificar el credential delegado con:

GET /api/v1/auth/organizations/{organizationId}/api-users/{apiKey}/mfa

Paso 4: Firmar Payloads con la Llave Privada

Una vez aprobado, el API user conserva la llave privada PEM y la usa localmente cuando un flujo protegido requiera firma delegada.

Ejemplo mínimo en Node.js:


import { createSign, readFileSync } from 'crypto'
 
const privateKey = readFileSync('./api-user-private.pem', 'utf8')
const payload = JSON.stringify(requestBody)
 
const signer = createSign('RSA-SHA256')
signer.update(payload)
signer.end()
 
const signature = signer.sign(privateKey, 'base64')

La forma exacta del payload y del campo de transporte depende del endpoint protegido. Usa la Referencia API como fuente de verdad.

Variante para Embedded Wallet

Para embedded wallet access, el flujo es similar pero usa:

POST /api/v1/auth/organizations/{organizationId}/wallet-access/request
POST /api/v1/auth/organizations/{organizationId}/wallet-access/prepare
POST /api/v1/auth/organizations/{organizationId}/wallet-access/approve

Cómo Funciona el Flujo

Buenas Prácticas

Trata los tokens MFA como artefactos de sesión de corta duración.
Si habilitas política transaccional, modela explícitamente el estado “pending approval” en tu app.
Expón los approval IDs en tus herramientas operativas para acelerar revisión.

Para una explicación completa de cómo se escriben y ordenan las reglas de política, y cómo se combinan con esquemas de aprobador único o quórum M-de-N, consulta Política Transaccional y Esquemas de Aprobación.