Pular para o conteúdo
MOONIPdocs
IntegraçãoManual
PTEN
Ir para o painel

Chaves de API

Chave de API é como toda requisição servidor-a-servidor na Moonip se autentica. Esta página é para quem administra as chaves da conta — se você só quer usar uma chave, veja Primeiros passos.

#Formato da chave

text
ak_live_<24-bytes-base64url>      ← produção
ak_test_<24-bytes-base64url>      ← teste
  • O texto em claro aparece exatamente uma vez, na emissão.
  • Do nosso lado guardamos só o fingerprint SHA-256 e um prefixo de 12 caracteres (ex.: ak_live_xyz) para exibir no painel.
  • Perdeu a chave? Não dá para recuperar — gire para emitir uma nova.

O prefixo exato varia por marca (aqui ak_live_ / ak_test_); o que é universal é o formato <prefix>_live_… / <prefix>_test_…. Nunca fixe um prefixo em código que classifica uma chave — os SDKs oficiais aceitam o prefixo de qualquer marca e expõem auxiliares isTestKey que leem o segmento _test_ em vez de comparar prefixo.

#Usando a chave na API

Chamadas servidor-a-servidor para /v1/* levam a chave no cabeçalho canônico Authorization: Bearer:

text
Authorization: Bearer ak_live_...

O cabeçalho legado apikey: ak_live_... continua aceito por compatibilidade (o gateway reescreve Bearer para a forma interna apikey). Integrações novas devem mandar Bearer e mais nada. Chave ausente ou inválida devolve 401.

Nunca logue a chave. Nem em log de aplicação, nem em saída de CI, nem em relatório de erro — o texto em claro é a credencial, e os fingerprints existem justamente para você falar de uma chave sem citá-la.

#Allowlist de IP

Uma conta pode restringir o tráfego por chave de API a uma lista de faixas CIDR. Nas rotas cobertas pela guarda, uma requisição vinda de um endereço fora da lista é recusada com 403 antes de a rota rodar — o mesmo envelope permission_error de Erros, e a chave em si não está com problema.

Escopo: a allowlist é aplicada nas rotas centrais da conta — carteiras, saques, transações, casos MED, api-keys e vizinhas. As rotas de movimentação de dinheiro /v1/charges, /v1/pix/charges, /v1/payments e /v1/webhooks não são cobertas pela allowlist por conta (o ip-restriction do gateway protege apenas /v1/admin).

Coloque na lista todo endereço de saída das suas integrações: servidores de produção, runners de CI, hosts de failover e os endereços de NAT das suas regiões de nuvem. Uma entrada errada aqui falha fechado — a requisição nem chega à checagem da chave, então um relatório de "chave válida, mas 403" costuma ser a allowlist.

Fale com o suporte (suporte@moonip.io) para incluir, alterar ou remover uma faixa; a lista é mantida por conta.

#Autenticação — estes endpoints usam JWT, não chave de API

Todos os endpoints /v1/api-keys/* são autenticados por JWT (o mesmo token de login do painel, devolvido por POST /v1/auth/login). Eles não passam pela autenticação por chave — seria um problema do ovo e da galinha.

text
Authorization: Bearer <JWT do painel>

A claim de conta do JWT limita toda operação — você só administra as chaves da sua própria conta.

Quem pode: qualquer membro ativo da conta lista as chaves. Emitir, girar e revogar exigem o papel de dono (OWNER) ou admin (ADMIN) da conta; outro papel recebe 403 com o código API_KEY_ROLE_REQUIRED.

#Endpoints

#Emitir uma chave

text
POST /v1/api-keys
bash
curl -X POST https://api.moonip.io/v1/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "label": "backend-producao", "test": false }'
CampoTipoObrigatórioDescrição
labelstringnãoTexto livre, até 64 caracteres. Aparece no painel, para gente ler.
testbooleanonãotrue emite uma chave ak_test_…. Padrão false.

Resposta 201 Created

json
{
  "id": "5b3a9c1d-...",
  "apiKey": "ak_live_F8A2K7M3N9PQRSTUVWXYZAB",
  "fingerprint": "9a3f7e1c5d8b2a40",
  "prefix": "ak_live_F8A",
  "label": "backend-producao",
  "createdAt": "2026-04-25T18:32:11.000Z",
  "mode": "live"
}

mode diz o ambiente da chave: test (sandbox, a cobrança não chega a um provedor real) ou live. É o mesmo critério que o gateway usa para rotear a cobrança; use este campo em vez de comparar o prefixo.

O apiKey só aparece aqui. Guarde num cofre de segredos na hora. O painel não mostra de novo nos acessos seguintes.

#Listar suas chaves

text
GET /v1/api-keys

Devolve só metadado — nunca o texto em claro.

json
{
  "data": [
    {
      "id": "5b3a9c1d-...",
      "prefix": "ak_live_F8A",
      "label": "backend-producao",
      "createdAt": "2026-04-25T18:32:11.000Z",
      "mode": "live"
    },
    {
      "id": "7f1c4e9a-...",
      "prefix": "ak_test_QRX",
      "label": "testes-ci",
      "createdAt": "2026-04-12T09:14:08.000Z",
      "mode": "test"
    }
  ],
  "access": { "canManage": true }
}

access.canManage diz se quem chamou pode emitir, girar e revogar (dono ou admin da conta).

#Girar uma chave

text
POST /v1/api-keys/{id}/rotate

Revoga a chave indicada e emite uma nova, de forma atômica. Faça isso com regularidade (a cada 90 dias é razoável) ou sempre que suspeitar de vazamento.

bash
curl -X POST https://api.moonip.io/v1/api-keys/5b3a9c1d-.../rotate \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "label": "backend-producao (girada em 2026-04-25)" }'

O formato da resposta é idêntico ao de emitir — incluindo o novo texto em claro.

A chave nova herda o ambiente da antiga: girar uma chave de teste emite outra de teste, e girar uma live emite outra live. O rótulo também é mantido, a menos que você mande um label novo. Um id que não é da sua conta devolve 404, e nada é revogado.

Atenção operacional: a chave antiga para de funcionar no instante em que essa chamada termina. Não existe janela de sobreposição. Ou você faz o deploy da chave nova nos seus servidores antes de chamar o rotate, ou emite uma chave paralela primeiro e revoga a antiga depois que a nova estiver no ar.

#Revogar uma chave

text
DELETE /v1/api-keys/{id}

Permanente — não tem desfazer.

bash
curl -X DELETE https://api.moonip.io/v1/api-keys/5b3a9c1d-... \
  -H "Authorization: Bearer $JWT"

Resposta 200 OK

json
{ "revoked": true }

#Checklist de segurança

  • Trate ak_live_… como senha — nunca commite, nunca logue, nunca cole no chat.
  • Guarde num cofre de segredos (Vault, 1Password, AWS Secrets Manager, variáveis de CI…).
  • Chaves diferentes por ambiente (ak_live_… em produção, ak_test_… em homologação e CI).
  • Uma chave por serviço, ou por máquina de desenvolvedor — assim revogar uma que vazou não derruba o resto.
  • Gire com agenda. Trimestral no mínimo; mensal em carga sensível.
  • Revogue na hora quando alguém sai da equipe.
  • Configure alerta nos eventos de auditoria de "chave emitida" e "chave girada".

#O que fica guardado onde

OndeO que tem lá
Gateway (autenticação)A chave em claro — usada para autenticar as requisições que chegam.
Banco MoonipReferência da conta, para busca reversa. Nunca o texto em claro.
Log de auditoriaEventos de emissão, rotação e revogação, com o id de quem fez e o fingerprint da chave.
PainelSó o prefixo e o rótulo.

#Dúvidas

P: Posso ter várias chaves de produção ao mesmo tempo? R: Pode — é justamente o que permite girar sem downtime e isolar por serviço. Não há limite rígido.

P: Perdi o texto em claro logo depois de criar. R: Ele se foi. Gire (ou revogue e emita outra) — não existe caminho de recuperação, por decisão de projeto.

P: Como sei qual chave fez qual requisição? R: O log de requisições do painel mostra o fingerprint da chave em toda chamada. Filtre por ele para atribuir o tráfego.

P: Dá para restringir uma chave a certos endpoints ou métodos? R: Ainda não. Escopo por chave está no roteiro. Hoje toda chave tem acesso completo à conta.