Chaves API

As chaves de API não são Membros com credenciais. Elas seguem um modelo de permissões próprio e mais simples:

Os dois modelos são intencionalmente separados. Os Membros recebem funções, perfis e granularidade por conta porque pessoas acumulam responsabilidades variadas. As Chaves seguem um modelo simples de escopo e contas porque a automação deve ser restrita, uniforme e fácil de auditar.

Uma chave de API combina duas seleções: o que ela pode fazer (suas permissões) e onde (suas contas).

Permissões

Mapeamento de contas

Cada chave é mapeada para uma ou mais contas, definidas no momento da criação e editáveis posteriormente. As permissões da chave se aplicam uniformemente a todas as contas selecionadas:

• Uma chave com Query funds e Create and modify orders em duas contas selecionadas pode consultar saldos e negociar em ambas, sem acessar nada além disso.
• Não há variação por conta dentro de uma chave. Se a sua automação precisar negociar em uma conta, mas apenas ler outra, use duas chaves. Isso mantém o raio de impacto de cada chave evidente.

Selecione uma conta específica quando necessário

As solicitações privadas de API usam a conta principal da Organização quando account_id é omitido:

Para operar em uma conta específica, passe account_id como parâmetro de consulta na URL:

Passe-o na URL, não no corpo da solicitação. Um account_id explícito tem precedência sobre o fallback da conta principal. Ele não expande o mapeamento de contas nem as permissões da chave. Se a chave não puder operar na conta selecionada, a solicitação será recusada.

Conectividade FIX

Chaves com permissões de ordens suportam conectividade FIX para negociação spot, além das APIs REST e WebSocket. Uma sessão FIX herda as mesmas permissões e mapeamento de contas da chave vinculada: opera apenas nas contas selecionadas por ela, dentro das suas permissões. Empresas que operam fluxo de ordens via FIX geralmente dedicam uma chave por sessão, com escopo nas contas negociadas pela mesa.

Configurações de segurança

A Governança da Organização se aplica tanto ao que as chaves fazem quanto à forma como são gerenciadas.

O que as chaves fazem

A regra de duas categorias para Membros se aplica às chaves da mesma forma:

• Operações diretas são executadas imediatamente. Negociação, Earn, consultas de saldo, consultas de ledger e exportações de dados são concluídas imediatamente, dentro das permissões e contas da chave.
• Operações governadas criam solicitações. Um saque ou alteração de endereço iniciado por uma chave segue o mesmo fluxo de um iniciado por um Membro: a política do workflow define se a operação é concluída imediatamente ou entra na fila de aprovação para revisão.

Uma chave só pode iniciar solicitações governadas. Chaves nunca têm permissão de Aprovação – a segregação de funções exige um Membro humano para cada aprovação, e um script não pode substituir esse julgamento. Quando a política de Solicitação de Saque exige duas aprovações, um saque iniciado por uma chave aguarda dois Membros, exatamente como ocorreria com um iniciado por um Membro.

Uma chamada bem-sucedida não é um saque concluído

Construa sua automação levando em conta essa assincronicidade. WithdrawFunds retorna approval_request_id junto com refid:

• O refid confirma que a solicitação existe, não que os fundos foram movimentados. O valor é bloqueado na conta de origem no momento do envio e só é liquidado após a aprovação da solicitação. Consulte Fundos bloqueados no momento do envio.
• O approval_request_id é o identificador da aprovação que o saque aguarda. Armazene-o junto ao seu próprio registro do saque.
• Saques aguardando aprovação não aparecem em WithdrawStatus. Uma solicitação rejeitada ou que expira não gera nenhum registro de saque, portanto a ausência em WithdrawStatus nunca significa que o saque não foi enviado.

Automações que tratam um refid como prova de conclusão vão reportar saques como liquidados enquanto ainda estão na fila de aprovação, e reconciliações que inferem "ausente em WithdrawStatus, portanto nunca enviado" estarão erradas tanto para solicitações pendentes quanto para as rejeitadas.

As chaves também não têm acesso aos fluxos administrativos. Gerenciar acesso da equipe, chaves de API, contas, endereços (além de iniciar solicitações de endereço) e políticas é exclusivo para Membros.

Como as chaves são gerenciadas

Criar, editar e revogar chaves de API é uma operação governada pelo fluxo dedicado Gerenciar Chaves de API, separado do Gerenciar Equipe e Acesso. Essa separação é importante por dois motivos:

• Administradores diferentes. Você pode permitir que um engenheiro de operações gerencie chaves sem poder alterar o acesso dos Membros, e vice-versa.
• Políticas diferentes. O gerenciamento de chaves pode ter seus próprios requisitos de aprovação. Muitas Organizações exigem aprovação independente para criar ou modificar uma chave – uma nova credencial é uma nova via de acesso às suas contas – mantendo a revogação ágil.

1. Acesse Chaves de API e selecione Criar chave.
2. Nomeie a chave de acordo com sua finalidade, o sistema que ela atende e o que faz, para que sua função seja evidente em revisões e eventos de segurança.
3. Selecione as permissões da chave.
4. Selecione as contas em que a chave vai operar. As permissões se aplicam a todas elas de forma uniforme.
5. Configure as definições de segurança: expiração, restrições de IP e nonce window.
6. Revise e confirme. Se a política Gerenciar Chaves de API exigir aprovação, a solicitação ficará pendente até que as aprovações necessárias sejam concluídas e a chave seja emitida.

A edição de permissões ou contas de uma chave e a revogação de uma chave seguem o mesmo fluxo de Governança.

A chamada criou uma solicitação de saque, e a política de Solicitação de Saque a mantém aguardando aprovação. Verifique a página Solicitações: a solicitação aparece lá com a chave como iniciadora, aguardando as aprovações necessárias dos Membros. Esse é o modelo de Governança funcionando conforme o esperado: a automação propõe, as pessoas aprovam.

O valor fica bloqueado na conta de origem enquanto a solicitação aguarda aprovação, já reservado para o saque. Acompanhe a solicitação usando o approval_request_id retornado com a chamada.

A conta com falha não está no mapeamento de contas da Chave. Uma Chave opera apenas nas contas selecionadas. Edite a Chave para adicionar a conta. Lembre-se de que o conjunto completo de permissões será aplicado a ela, já que Chaves não têm variação por conta. Se isso for amplo demais, crie uma segunda chave com escopo limitado à nova conta.

Uma única chave não pode ter permissões diferentes por conta. Crie duas Chaves: uma de negociação mapeada para a conta A e uma somente leitura mapeada para a conta B. Chaves com escopo mais restrito também são mais fáceis de auditar e mais seguras de revogar.

O fluxo de trabalho Gerenciar Chaves de API provavelmente exige aprovação, e a solicitação ainda está pendente. A chave é emitida e seu segredo exibido somente após todas as aprovações necessárias serem concluídas. Verifique o status da solicitação na página Solicitações.

Não. A aprovação sempre exige um Membro humano. Esta é uma regra do sistema, não uma política configurável: é o que torna a aprovação multiparticipante relevante quando a automação inicia movimentações de fundos.