API de parceiros: oferecer o 4Keyless com a sua marca

A API de parceiros é para quem constrói a própria interface sobre o 4Keyless (white-label): o seu backend cria as contas dos seus clientes, recebe a key de integração de cada um e opera essas contas por API. O cliente final pode nunca abrir o painel do 4Keyless.

A parceria é criada pela equipe do 4Keyless. Se você quer ser parceiro, comece por Afiliados e parceria.

As duas keys

As duas vão em Authorization: Bearer <key>, na base https://api.4keyless.io/api/v1. A key de parceiro nunca entra na conta de um cliente; dentro da conta, você usa a key de integração daquele cliente, e a key do cliente A não opera o cliente B.

Guarde as duas só no backend. Cada uma pode ter faixas de IP permitidas (allowed_cidrs) e validade de 1 a 365 dias ou indeterminada; o padrão recomendado é 90 dias, com rotação.

Onde gerir as keys

A equipe do 4Keyless emite a primeira key de parceiro. Depois, os administradores da sua conta veem o menu Parceria no painel, com a carteira, o consumo, os projetos e as keys:

• emitir, rotacionar e revogar keys de parceiro (exige MFA ativo no seu usuário; a key antiga segue valendo por até 24 horas depois da rotação);
• criar clientes e emitir ou regenerar a key de integração de cada um, enquanto o admin do cliente não desligar a integração.

Toda key aparece uma única vez. Anote na hora.

Fluxo de um cliente novo

1. GET /partner/me: confira escopos, planos permitidos, cota e projetos da key.
2. POST /partner/tenants, com o cabeçalho Idempotency-Key: cria o cliente, envia o convite ao admin dele (que define a senha) e deixa a primeira key de integração disponível por 72 horas.
3. POST /partner/tenants/{id}/integration/bootstrap: emite essa key de integração uma única vez. Se a resposta se perder, a próxima key sai do menu Parceria (regenerar) ou do painel do cliente; repetir o bootstrap não cria outra.
4. Com a key de integração, use as rotas da API de integração. Acompanhe a validade por key_expires_at em GET /integration/me e rotacione com POST /integration/key/rotate.

curl -X POST https://api.4keyless.io/api/v1/partner/tenants \
  -H "Authorization: Bearer $FKL_PARTNER_KEY" \
  -H "Idempotency-Key: cliente-exemplo-0001" \
  -H 'Content-Type: application/json' \
  -d @cliente.json

O corpo de POST /partner/tenants e de todas as outras rotas está na referência, no painel: /api-docs, documento Parceiros. Esse documento só aparece para usuários de uma conta com parceria.

Idempotência

POST /partner/tenants exige Idempotency-Key, de 8 a 200 caracteres, único por operação do seu lado.

• Mesma chave e mesmo corpo: 200 com replayed: true e o cabeçalho Idempotent-Replayed: true, sem efeito novo.
• Mesma chave com corpo diferente: 409 idempotency_conflict.
• GET /partner/operations/{id} mostra o andamento dos passos depois da criação (cobrança e e-mail de convite).

Executar em nome de um agente do cliente

Uma execução sempre roda em nome de um agente do cliente, com as liberações e os titulares dele. Com a key de integração, POST /runs recebe o agent_id; para agente humano, a integração precisa também do escopo agents:delegate e do papel admin. A trilha registra a sua integração como quem pediu. Os escopos runs:* e agents:delegate não vêm por padrão: a plataforma os concede ao seu projeto, e o cliente, à integração.

Limites

Por minuto: 120 chamadas por key e 300 por IP em leitura; 60 escritas por key de integração. Os limites continuam valendo mesmo com instabilidade no 4Keyless.

Quando a parceria ou a integração termina

Se a parceria for suspensa ou encerrada, ou se o admin do cliente desligar a integração, a próxima chamada recebe 403 delegation_blocked, com reason igual a partner_suspended, partner_terminated ou user_inactive. Os recursos que você criou no cliente continuam com ele. Chaves de agente que você emitiu no cliente não são revogadas automaticamente.

Se algo der errado