Autenticação

A Inyo usa chaves de API para controlar com segurança o acesso às suas APIs. Todas as requisições devem ser autenticadas — requisições não autenticadas são rejeitadas pelo firewall.

Antes mesmo de a autenticação se aplicar, sua conexão deve passar por duas verificações em nível de rede: um certificado de cliente TLS mútuo (mTLS) e uma lista de permissões de IP fixo. Veja Conectividade.

Credenciais

Durante o onboarding, a Inyo fornece as seguintes credenciais:

Camadas de Autenticação

A API usa um modelo de autenticação em duas camadas. Diferentes endpoints exigem diferentes combinações de credenciais:

Autenticação em Nível de Tenant

Usada para gestão de contas, conformidade e operações de leitura.

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

Endpoints que usam autenticação de Tenant:

• CRUD de Pessoa/Empresa (POST /people, PATCH /people/{id}, etc.)
• Níveis de conformidade (GET /participants/{id}/complianceLevels)
• Upload de documentos e status de verificação (POST /people/{id}/documents/...)
• Gestão de webhooks (POST /webhooks, GET /webhooks, DELETE /webhooks/{id})
• Gestão de agentes (POST /agents)
• Verificação de endereço (GET /addresses/check)

Autenticação em Nível de Agente

Usada para operações transacionais que movimentam dinheiro. Requer tanto a chave de API do Tenant quanto as credenciais do 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 usam autenticação de Agente:

• Cotações (POST /payout/quotes)
• Todas as operações de transação (/fx/transactions... — criar, obter, listar, histórico de status, cancelar, metadados, limites)
• Contas de financiamento (POST /payout/participants/{id}/fundingAccounts)
• Contas de destinatário (POST /payout/participants/{id}/recipientAccounts/gateway)
• Dados de referência (destinos, bancos, schemas de destinatário/conta/transação)
• Operações de segredo de assinatura de webhook (POST/DELETE /webhooks/{id}/secret) — sensíveis à segurança, portanto exigem a identidade de um agente para a trilha de auditoria
• Operações de carteira

Aprovação do Agente Obrigatória: Agentes recém-criados começam com o status PENDING_APPROVAL e devem ser aprovados pela equipe de conformidade da Inyo antes de poderem executar transações. Antes da aprovação, requisições autenticadas com agente retornarão 403 Forbidden.

As chaves de API do agente são exibidas uma única vez. Quando você cria um agente via POST /organizations/{tenant}/agents, a apiKey bruta aparece somente na resposta de criação — ela é armazenada com hash e não pode ser recuperada depois. Guarde-a com segurança no momento da criação.

Headers Obrigatórios

Inclua os seguintes headers em todas as requisições:

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

Para endpoints autenticados com agente, inclua também:

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

Ambientes

Sandbox e produção usam credenciais separadas. Nunca use chaves de sandbox em produção nem vice-versa.

Boas Práticas de Segurança

• Nunca exponha chaves de API em código de frontend. Use um padrão Backend-for-Frontend (BFF) — seu servidor guarda os segredos e faz proxy das requisições para a Inyo.
• Rotacione as chaves se suspeitar de comprometimento. Entre em contato com nossa equipe de vendas para a rotação de chaves.
• Restrinja o acesso à rede — use lista de permissões de IP em produção, se suportada pelo seu plano.
• Use apenas HTTPS — todos os endpoints da Inyo exigem TLS. Requisições em HTTP puro são rejeitadas.

Respostas de Erro