Chaves de API

As chaves de API permitem acessar a REST API do badges.ninja de forma programática. Use-as para automatizar a criação, emissão e gestão de distintivos a partir das suas próprias aplicações.

Criando uma chave de API

1. Abra a página Chaves de API na barra lateral.
2. Clique em Criar chave de API. Um formulário embutido abre:

3. Dê um nome à chave e clique em Criar. A chave completa é revelada uma única vez em um banner verde:

4. Copie a chave imediatamente — a chave completa só é exibida uma vez. Se perder, será necessário criar outra. Depois de fechar o banner, o painel só exibe o prefixo da chave (ex.: bws_a1b2c3d4...); a chave completa permanece armazenada no servidor para autenticar suas requisições:

Cada linha também mostra quando a chave foi criada e, depois de usada, um carimbo de último uso, para você identificar chaves obsoletas.

Escopos de acesso

Ao criar uma chave, você pode torná-la somente leitura ou deixá-la com acesso completo:

Escopo	Permite
Acesso completo (padrão)	Leitura e escrita — listar dados e criar, emitir, atualizar ou excluir.
Somente leitura	Apenas requisições GET seguras. Qualquer requisição que altere dados (POST, PUT, PATCH, DELETE) é rejeitada com 403 Forbidden.

Use uma chave somente leitura para integrações que precisam apenas ler os seus dados (relatórios, painéis, backups), de modo que uma chave vazada não possa alterar nada. Marque Chave somente leitura no formulário de criação; chaves somente leitura exibem um selo Somente leitura na lista. Chaves criadas antes de os escopos existirem mantêm o acesso completo.

Formato da chave

As chaves de API usam o prefixo bws_ seguido de uma string hexadecimal de 32 caracteres:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Usando chaves de API nas requisições

Inclua a chave de API no cabeçalho X-Api-Key de toda requisição:

curl -X GET https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here"

Consulte a página Autenticação para todos os detalhes sobre autenticação da API.

Limites de chaves por plano

A quantidade de chaves de API que você pode criar depende do seu plano:

Plano	Limite de chaves de API
Free	1
Starter (US$ 9/mês)	5
Pro (US$ 29/mês)	20

Expiração da chave

Toda chave de API expira um ano após ser criada. Assim que uma chave expira, ela deixa de autenticar requisições, exatamente como se tivesse sido excluída. Crie uma nova chave antes de a antiga vencer para evitar interrupções.

Excluindo uma chave

1. Abra a página Chaves de API.
2. Encontre a chave que deseja excluir.
3. Clique em Excluir.
4. Confirme a exclusão.

Depois de excluída, a chave para de funcionar imediatamente. Qualquer aplicação que esteja usando-a receberá erros de autenticação.