Emitir uma chave de API

Emite uma chave nova e devolve o segredo UMA única vez. Guarde-o na emissão: nenhuma rota o mostra de novo.

POSThttps://api.navenaut.com/api-keys/

Autenticação

A sessão do painel autentica esta rota, e ela é lida de forma autoritativa: não há parâmetro em que o chamador aponte para outra conta.

Esta rota não exige escopo nomeado — o que não quer dizer que ela seja aberta: sem a credencial acima ela recusa.

Exige sessão de vendedor. A chave de API não autentica esta rota: uma chave não pode emitir nem revogar outra chave.

Parâmetros

Corpo da requisição

application/json.

Campo	Tipo	Descrição
`allProducts`	booleano	Não é mais aceito. Enviar `true` recusa a emissão com API_KEY_PRODUCTS_INVALID. Chaves antigas de todos os produtos continuam valendo e aparecem na listagem com productRefs nulo.
`family`	um de: `live`, `test`	O ambiente da chave. A família decide contra qual ambiente ela escreve, e ela vai no prefixo do segredo.
`label`obrigatório	texto	Nome livre para você reconhecer a chave depois. Não tem efeito sobre a autorização.
`productRefs`obrigatório	arranjo de texto (uuid)	Lista obrigatória com exatamente um identificador de produto da sua empresa. A chave fica presa a esse produto, e é ele que separa as vendas da chave nos filtros de relatório. Cada cobrança continua enviando productRef, que precisa ser esse produto. Em Test, a emissão atualiza a cópia do produto e dos splits no ambiente de teste para as próximas cobranças, sem alterar vendas anteriores.
`reportName`	texto	Não é mais aceito. Qualquer valor recusa a emissão com API_KEY_PRODUCTS_INVALID. Chaves antigas com nome de relatório continuam o devolvendo na listagem.
`scopes`obrigatório	arranjo de texto	Os escopos que a chave pode exercer. Escopo desconhecido recusa a emissão inteira, em vez de emitir uma chave com menos poder do que você pediu.

{
  "family": "live",
  "label": "Loja Exemplo",
  "productRefs": [
    "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06"
  ],
  "scopes": [
    "exemplo"
  ]
}

Respostas

201 · criado

{
  "createdAt": "2026-01-15T12:00:00.000Z",
  "id": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
  "label": "Loja Exemplo",
  "prefix": "exemplo",
  "productRefs": [
    "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06"
  ],
  "reportName": "exemplo",
  "scopes": [
    "balance:read"
  ],
  "secret": "valor-de-exemplo-nao-use",
  "tail": "exemplo"
}

Chave emitida; o segredo está no corpo e não volta.

403 · proibido

Sua conta não tem KYC aprovado em nenhum adquirente. Nenhuma chave foi emitida.

422 · corpo inválido

Produtos ausentes ou inválidos, ou escopo desconhecido. Nenhuma chave foi emitida; somente a recusa de escopo traz supported.

503 · indisponível

Nenhuma chave foi emitida, e o code diz se vale repetir. SANDBOX_UNAVAILABLE: esta instalação não tem ambiente de teste provisionado. Peça uma chave de produção, porque repetir não resolve. SANDBOX_MIRROR_FAILED: o ambiente existe e algo falhou agora, então repita em instantes.

Erros desta rota

Status	Código	Quando	O que fazer
403	`API_KEY_KYC_NOT_APPROVED`	Sua conta não tem KYC aprovado em nenhum adquirente. Vale para quem nunca enviou, quem enviou e está em análise, e quem foi recusado: as três situações recusam a emissão do mesmo jeito, e a resposta não diz qual delas é a sua.	Confira `GET /kyc/status` e complete o envio se ainda não completou. Uma chave já emitida antes desta conferência continua valendo mesmo que o KYC mude depois: a checagem vale só na emissão.
422	`API_KEY_PRODUCTS_INVALID`	O produto não existe ou é de outra empresa (as duas situações recebem a mesma recusa), ou o pedido trouxe allProducts ou reportName, que não são mais aceitos. Lista vazia ou com mais de um produto é recusada antes, pela validação do corpo.	Envie productRefs com um único produto da empresa atual, sem allProducts e sem reportName, e reenvie. O vínculo não publica rascunhos nem libera produtos indisponíveis.
422	`API_KEY_SCOPE_UNKNOWN`	Um dos escopos que você pediu não existe nesta instalação. A emissão inteira foi recusada de propósito: emitir a chave sem o escopo desconhecido entregaria a você uma chave com menos poder do que a que você pediu, e você só descobriria isso na primeira chamada recusada.	Leia `supported` na resposta, que traz a lista dos escopos que existem, corrija a lista enviada e reenvie. Nenhuma chave foi emitida, então não há nada a revogar.
503	`SANDBOX_UNAVAILABLE`	Você pediu uma chave da família de teste e esta instalação não tem ambiente de teste provisionado. Não é falha momentânea: o ambiente não existe.	Peça uma chave de produção, ou fale com quem opera a instalação para provisionar o ambiente de teste. Repetir a emissão não muda o resultado.
503	`SANDBOX_MIRROR_FAILED`	O ambiente de teste existe e a cópia da chave para dentro dele não completou agora. Nenhuma chave foi emitida: uma chave que valesse só de um lado seria pior do que nenhuma.	Repita a emissão em instantes. Diferente do caso anterior, aqui repetir resolve.

Os códigos são estáveis e fazem parte do contrato. A lista completa, com todos os vocabulários, está na tabela de erros.

Próximo passo

Criar uma cobrança com a chave