Autenticación

Inyo utiliza claves de API para controlar de forma segura el acceso a sus APIs. Todas las solicitudes deben estar autenticadas — las solicitudes no autenticadas son rechazadas por el firewall.

Antes de que la autenticación siquiera aplique, su conexión debe superar dos verificaciones a nivel de red: un certificado de cliente TLS mutuo y una lista de IPs fijas permitidas. Vea Conectividad.

Credenciales

Durante el onboarding, Inyo le proporciona las siguientes credenciales:

Capas de autenticación

La API usa un modelo de autenticación de doble capa. Diferentes endpoints requieren diferentes combinaciones de credenciales:

Autenticación a nivel de tenant

Se usa para la gestión de cuentas, cumplimiento y operaciones de lectura.

GET /organizations/{tenant}/people/{personId}
Content-Type: application/json
Accept: application/json
x-api-key: {your_tenant_api_key}

Endpoints que usan autenticación de Tenant:

• CRUD de Persona/Empresa (POST /people, PATCH /people/{id}, etc.)
• Niveles de cumplimiento (GET /participants/{id}/complianceLevels)
• Carga de documentos y estado de verificación (POST /people/{id}/documents/...)
• Gestión de webhooks (POST /webhooks, GET /webhooks, DELETE /webhooks/{id})
• Gestión de agentes (POST /agents)
• Verificación de direcciones (GET /addresses/check)

Autenticación a nivel de agente

Se usa para operaciones transaccionales que mueven dinero. Requiere tanto la clave de API de Tenant como las credenciales de Agente.

POST /organizations/{tenant}/fx/transactions
Content-Type: application/json
Accept: application/json
x-api-key: {your_tenant_api_key}
x-agent-id: {your_agent_id}
x-agent-api-key: {your_agent_api_key}

Endpoints que usan autenticación de Agente:

• Cotizaciones (POST /payout/quotes)
• Todas las operaciones de transacciones (/fx/transactions... — crear, obtener, listar, historial de estados, cancelar, metadatos, límites)
• Cuentas de fondeo (POST /payout/participants/{id}/fundingAccounts)
• Cuentas de destinatarios (POST /payout/participants/{id}/recipientAccounts/gateway)
• Datos de referencia (destinos, bancos, esquemas de destinatario/cuenta/transacción)
• Operaciones del secreto de firma de webhooks (POST/DELETE /webhooks/{id}/secret) — sensibles en materia de seguridad, por lo que requieren una identidad de agente para el rastro de auditoría
• Operaciones de billetera

Se requiere aprobación del agente: Los agentes recién creados comienzan en estado PENDING_APPROVAL y deben ser aprobados por el equipo de cumplimiento de Inyo antes de poder ejecutar transacciones. Antes de la aprobación, las solicitudes autenticadas con agente devolverán 403 Forbidden.

Las claves de API de agente se muestran una sola vez. Cuando usted crea un agente mediante POST /organizations/{tenant}/agents, la apiKey en bruto aparece solo en la respuesta de creación — se almacena en forma de hash y no puede recuperarse después. Guárdela de forma segura en el momento de la creación.

Encabezados requeridos

Incluya los siguientes encabezados en cada solicitud:

Content-Type: application/json
Accept: application/json
x-api-key: {your_tenant_api_key}

Para los endpoints autenticados con agente, incluya también:

x-agent-id: {your_agent_id}
x-agent-api-key: {your_agent_api_key}

Entornos

Sandbox y producción usan credenciales separadas. Nunca use claves de sandbox en producción ni viceversa.

Mejores prácticas de seguridad

• Nunca exponga claves de API en código frontend. Use un patrón Backend-for-Frontend (BFF) — su servidor guarda los secretos y actúa como proxy de las solicitudes hacia Inyo.
• Rote las claves si sospecha un compromiso. Contacte a nuestro equipo de ventas para la rotación de claves.
• Restrinja el acceso de red — use listas de IPs permitidas en producción si su plan lo admite.
• Use solo HTTPS — todos los endpoints de Inyo exigen TLS. Las solicitudes HTTP sin cifrar son rechazadas.

Respuestas de error