Chaves de API

As chaves de API não são Membros com credenciais. Têm o seu próprio modelo de permissões, mais simples:

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

Uma chave de API combina duas seleções: o que pode fazer (as suas permissões) e onde (as 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 aplicam-se uniformemente a todas as contas selecionadas:

• Uma chave com as permissões Consultar fundos e Criar e modificar ordens em duas contas selecionadas pode ler saldos e negociar em ambas, sem aceder a mais nada.
• Não existe variação por conta dentro de uma chave. Se a sua automatização precisar de negociar numa conta mas apenas ler outra, utilize duas chaves. Assim, o âmbito de impacto de cada chave mantém-se evidente.

Selecione uma conta específica quando necessário

Os pedidos privados à API utilizam a conta principal da Organização quando account_id é omitido:

Para operar numa conta específica, passe account_id como parâmetro de consulta no URL:

Passe-o no URL, não no corpo do pedido. Um account_id explícito tem precedência sobre a conta principal por defeito. Não expande o mapeamento de contas nem as permissões da chave. Se a chave não puder operar na conta selecionada, o pedido é recusado.

Conectividade FIX

As chaves com permissões de ordens suportam conectividade FIX para negociação à vista, em paralelo com as APIs REST e WebSocket. Uma sessão FIX herda as permissões e o mapeamento de contas da chave associada: negoceia apenas nas contas selecionadas pela chave, dentro das suas permissões. As empresas com fluxo de ordens FIX dedicam normalmente uma chave por sessão, limitada às contas da respetiva mesa de negociação.

Definições de segurança

A governação da Organização aplica-se ao que as chaves fazem e à forma como são geridas.

O que as chaves fazem

A regra das duas categorias para os Membros aplica-se igualmente às chaves:

• As operações diretas são executadas imediatamente. Negociação, Earn, consultas de saldo, consultas ao livro-razão e exportações de dados concluem de imediato, dentro das permissões e contas da chave.
• As operações governadas criam pedidos. Um levantamento ou alteração de endereço iniciado por uma chave percorre o mesmo fluxo que um iniciado por um Membro: a política do fluxo de trabalho determina se conclui de imediato ou aguarda na fila de aprovação para revisão humana.

Uma chave só pode iniciar pedidos governados. As chaves nunca têm a permissão de Aprovação – a separaçã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 Pedido de Levantamento requer duas aprovações, um levantamento iniciado por uma chave aguarda dois Membros, exatamente como um iniciado por um Membro.

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

Construa a sua automação tendo em conta essa assincronicidade. WithdrawFunds devolve approval_request_id juntamente com refid:

• O refid confirma que o pedido existe, não que os fundos foram movimentados. O montante fica bloqueado na conta de origem no momento da submissão e só é liquidado após a aprovação do pedido. Consulte Fundos bloqueados no momento da submissão.
• O approval_request_id é o identificador da aprovação que o levantamento aguarda. Guarde-o junto ao seu próprio registo do levantamento.
• Os levantamentos a aguardar aprovação não aparecem em WithdrawStatus. Um pedido rejeitado ou expirado não gera qualquer registo de levantamento, pelo que a ausência de WithdrawStatus nunca significa que o levantamento não foi submetido.

A automatização que trate um refid como prova de conclusão reportará levantamentos como liquidados enquanto estes aguardam na fila de aprovação, e a reconciliação que infira «ausente de WithdrawStatus, logo nunca submetido» estará errada tanto para pedidos pendentes como para pedidos rejeitados.

As chaves também não têm acesso aos fluxos de trabalho administrativos. A gestão de acessos da equipa, chaves de API, contas, endereços (para além de iniciar pedidos de endereço) e políticas é exclusiva dos Membros.

Como as chaves são geridas

Criar, editar e revogar chaves de API é uma operação controlada pelo fluxo de trabalho dedicado Manage API Keys, separado do Manage Team & Access. A separação é relevante em dois aspetos:

• Administradores distintos. Pode permitir que um engenheiro de operações gira as chaves sem qualquer capacidade de alterar o acesso dos Membros, e vice-versa.
• Políticas distintas. A gestão de chaves pode ter os seus próprios requisitos de aprovação. Muitas Organizações exigem aprovação independente para criar ou modificar uma chave – uma nova credencial representa um novo acesso às contas –, mantendo ao mesmo tempo a revogação ágil.

1. Aceda a Chaves de API e selecione Criar chave.
2. Dê à chave um nome que reflita a sua finalidade – o sistema que serve e o que faz –, para que a sua função seja imediatamente identificável em auditorias 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 aplicam-se de forma uniforme a todas elas.
5. Configure as definições de segurança: expiração, restrições de IP e intervalo de valor aleatório.
6. Reveja e confirme. Se a política de Gestão de Chaves de API exigir aprovação, o pedido aguarda as aprovações necessárias antes de a chave ser emitida.

A edição das permissões ou contas de uma chave e a sua revogação seguem o mesmo processo de governação.

A chamada criou um pedido de levantamento que a política de Pedidos de Levantamento está a reter para aprovação. Consulte a página de Pedidos: o pedido aparece aí com a chave como iniciadora, a aguardar as aprovações necessárias dos membros. É o modelo de governação a funcionar como previsto: a automação propõe, os humanos aprovam.

O montante fica bloqueado na conta de origem enquanto o pedido aguarda, pelo que já se encontra reservado para o levantamento. Acompanhe o pedido através do approval_request_id devolvido com a chamada.

A conta em causa não está no mapeamento de contas da chave. Uma chave opera apenas nas contas selecionadas. Edite a chave para adicionar a conta, tendo em conta que o conjunto completo de permissões da chave se aplicará a essa conta, uma vez que as chaves não admitem variação por conta. Se esse âmbito for demasiado abrangente, crie uma segunda chave limitada à nova conta.

Uma única chave não pode ter permissões diferentes por conta. Crie duas chaves: uma chave de negociação associada à conta A e uma chave só de leitura associada à conta B. Chaves mais restritas são também mais fáceis de auditar e mais seguras de revogar.

O fluxo de trabalho Gerir Chaves de API provavelmente requer aprovação, e o pedido ainda está pendente. A chave só é emitida, e o respetivo segredo apresentado, após a recolha das aprovações necessárias. Verifique o estado do pedido na página Pedidos.

Não. A aprovação requer sempre um Membro humano. Esta é uma regra do sistema, não uma política configurável – é o que torna a aprovação multi-parte significativa quando a automação inicia movimentos de fundos.