Pular para o conteúdo principal

Autenticação de integrações

Integrações de servidor usam chaves de API da organização. A chave tem o formato sgk_live_<prefixo>_<segredo> em produção e sgk_test_<prefixo>_<segredo> nos demais ambientes, e é enviada no header Authorization como Bearer. O segredo completo só aparece na resposta de criação (campo secret).

Preparar a chave​

Uma pessoa autorizada cria a chave no backoffice ou por POST /api/v1/api-keys, usando uma sessão humana válida. A operação exige identity.api_keys.manage.

O corpo aceita name (obrigatório), permission_keys, expires_at, allowed_cidrs e from_role_id. Quando permission_keys vem vazio e from_role_id é informado, a chave recebe um retrato das permissões do papel; alterações posteriores no papel não ampliam a chave. Uma chave só pode receber permissões que a própria pessoa que a cria possui, e nunca as permissões da plataforma (platform.*), identity.api_keys.manage e audience.settings.manage (api_key_forbidden_permission).

Defina apenas as permissões necessárias para o fluxo. Uma chave que lê dívidas não precisa administrar membros ou webhooks. Vincule uma expiração e restrições de rede quando forem adequadas ao sistema consumidor.

Fazer uma leitura​

O exemplo usa variáveis já provisionadas no processo e não contém uma credencial real:

curl --fail-with-body \
  "$COBRES_API_URL/api/v1/debts?limit=20" \
  -H "Authorization: Bearer $COBRES_API_KEY" \
  -H 'Accept: application/json'

A chave pertence a uma organização imutável. Não há um header de organização que transforme uma chave em acesso a outro cliente.

Restrições de ator​

As chaves são para comunicação entre servidores. Uma requisição com sgk_ e header Origin é recusada com 401 origin_not_allowed. Não distribua essa credencial em um aplicativo web ou móvel.

A presença da permissão também não torna toda rota automatizável. Algumas operações, como administração de conexões financeiras, aprovação e ações financeiras específicas, exigem ator humano. A caixa de entrada de notificações também possui portas restritas à identidade humana.

Chaves de API também recebem 403 actor_not_allowed nas rotas de login, renovação de sessão, senha, convites de acesso, sessões e dados pessoais da conta (/me/...), /oauth e /platform. Uma chave de API não autentica no plano Audience. O portal e o portal do credor usam o próprio fluxo de sessão externa.

Ciclo de vida​

GET /api-keys lista as chaves visíveis e GET /api-keys/{key_id} consulta uma (identity.api_keys.read). PATCH /api-keys/{key_id} altera name, permission_keys, expires_at e allowed_cidrs, e POST /api-keys/{key_id}/revoke revoga o acesso (identity.api_keys.manage). Use o código público de quatro caracteres retornado em code no lugar de key_id.

Para trocar uma chave sem interromper o consumidor, crie a substituta, atualize o sistema, confirme as leituras e revogue a anterior. Nunca registre o header de autorização em logs, tickets ou exemplos públicos.