Authentication

Inyo uses API keys to securely control access to its APIs. All requests must be authenticated — unauthenticated requests are rejected by the firewall.

Before authentication even applies, your connection must clear two network-level checks: a mutual TLS client certificate and a fixed-IP allowlist. See Connectivity.

Credentials

During onboarding, Inyo provides you with the following credentials:

Authentication Layers

The API uses a dual-layer authentication model. Different endpoints require different credential combinations:

Tenant-Level Authentication

Used for account management, compliance, and read operations.

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

Endpoints using Tenant auth:

• Person/Company CRUD (POST /people, PATCH /people/{id}, etc.)
• Compliance levels (GET /participants/{id}/complianceLevels)
• Document uploads and verification status (POST /people/{id}/documents/...)
• Webhook management (POST /webhooks, GET /webhooks, DELETE /webhooks/{id})
• Agent management (POST /agents)
• Address verification (GET /addresses/check)

Agent-Level Authentication

Used for transactional operations that move money. Requires both the Tenant API key and Agent credentials.

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 using Agent auth:

• Quotes (POST /payout/quotes)
• All transaction operations (/fx/transactions... — create, get, list, status history, cancel, metadata, limits)
• Funding accounts (POST /payout/participants/{id}/fundingAccounts)
• Recipient accounts (POST /payout/participants/{id}/recipientAccounts/gateway)
• Reference data (destinations, banks, recipient/account/transaction schemas)
• Webhook signing-secret operations (POST/DELETE /webhooks/{id}/secret) — security-sensitive, so they require an agent identity for the audit trail
• Wallet operations

Agent Approval Required: Newly created agents start in PENDING_APPROVAL status and must be approved by the Inyo compliance team before they can execute transactions. Before approval, agent-authenticated requests will return 403 Forbidden.

Agent API keys are shown once. When you create an agent via POST /organizations/{tenant}/agents, the raw apiKey appears only in the creation response — it is stored hashed and cannot be retrieved later. Save it securely at creation time.

Required Headers

Include the following headers on every request:

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

For agent-authenticated endpoints, also include:

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

Environments

Sandbox and production use separate credentials. Never use sandbox keys in production or vice versa.

Security Best Practices

• Never expose API keys in frontend code. Use a Backend-for-Frontend (BFF) pattern — your server holds the secrets and proxies requests to Inyo.
• Rotate keys if you suspect compromise. Contact our sales team for key rotation.
• Restrict network access — use IP allowlisting in production if supported by your plan.
• Use HTTPS only — all Inyo endpoints enforce TLS. Plain HTTP requests are rejected.

Error Responses