Pular para o conteúdo principal

​
Conta de Serviço

Contas de serviço permitem que sua aplicação acesse a Banking API de forma programática. Cada conta de serviço possui:
  • Access ID - Identificador único (UUID)
  • Chave Pública - Para verificar assinaturas
  • Permissões - Controle granular de acesso
  • IPs Permitidos - Lista de IPs autorizados

​
Criando uma Conta de Serviço

​
1. Acesse o Dashboard

Navegue até Configurações → Credenciais API no dashboard Conta Digital.

​
2. Clique em “Nova Credencial”

Preencha os campos:
CampoDescrição
DescriçãoNome para identificar a credencial (ex: “Backend Produção”)
Chave PúblicaSua chave Ed25519 no formato ssh-ed25519 ...
PermissõesSelecione as permissões necessárias
IPs PermitidosLista de IPs ou CIDRs autorizados (opcional, padrão: 0.0.0.0/0, ::/0)

​
3. Salve o Access ID

Após criar, você receberá um Access ID (UUID). Este é o valor do header x-access-id nas requisições.
O Access ID é exibido apenas uma vez. Copie e guarde em local seguro.

​
Permissões Disponíveis

PermissãoDescriçãoEndpoints
view_balanceVer saldoGET /v1/balance
view_account_detailsVer detalhes da contaGET /v1/account, GET /v1/account-limits
view_transactionsVer transaçõesGET /v1/transactions, GET /v1/transactions/{id}
list_dict_keysListar chaves PIXGET /v1/dict-keys
initiate_paymentCriar transferênciasPOST /v1/transfers
cancel_scheduled_paymentsCancelar pagamentosPagamentos agendados
refund_transactionEstornar transaçõesEstornos
Aplique o princípio do menor privilégio. Conceda apenas as permissões necessárias para sua aplicação.

​
IPs Permitidos

Configure uma lista de IPs autorizados para maior segurança. Formatos aceitos: 
192.168.1.100        # IP único
192.168.1.0/24       # Range CIDR
2001:db8::1          # IPv6
Se nenhum IP for configurado, requisições de qualquer IP serão aceitas (0.0.0.0/0 e ::/0).

​
Gerenciando Contas de Serviço

​
Listar Contas

No dashboard, veja todas as contas de serviço ativas com:
  • Descrição
  • Access ID (parcialmente oculto)
  • Permissões
  • IPs permitidos

​
Excluir Conta

Para revogar acesso, exclua a conta de serviço. A exclusão é imediata e permanente.
Após excluir, todas as requisições usando aquele Access ID serão rejeitadas com 401 Unauthorized.

​
Fluxo Completo

1

Gerar Chaves

Crie um par de chaves Ed25519 usando ssh-keygen ou outro método. Ver instruções →
2

Criar Conta de Serviço

No dashboard, cadastre a chave pública e configure permissões.
3

Guardar Credenciais

Salve o Access ID e a chave privada em local seguro (variáveis de ambiente, secret manager).
4

Fazer Requisições

Use a chave privada para assinar requisições. Ver autenticação →

​
Boas Práticas

Rotacione Periodicamente

Crie novas credenciais regularmente e revogue as antigas.

Ambiente Separado

Use contas de serviço diferentes para dev, staging e produção.

Permissões Mínimas

Conceda apenas as permissões estritamente necessárias.

Restrinja IPs

Configure IPs permitidos para seus servidores de produção.