Chaves de API

As chaves de API permitem acessar a API REST do badges.ninja de forma programática. Use-as para automatizar a criação, a emissão e o gerenciamento de distintivos a partir dos seus próprios aplicativos.

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 em linha é aberto:

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

4. Copie a chave imediatamente — a chave completa só é exibida uma vez. Se você a perder, precisará criar uma nova. Depois que você fechar o banner, o painel mostra apenas o prefixo da chave (por exemplo, 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 data/hora de último uso, para você identificar chaves sem uso.

Escopos de acesso

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

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

Use uma chave somente leitura em integrações que só precisam ler seus dados (relatórios, painéis, backups), para que o vazamento de uma chave não permita alterar nada. Marque Chave somente leitura no formulário de criação; as chaves somente leitura exibem um selo Somente leitura na lista. As chaves criadas antes da existência dos escopos mantêm acesso total.

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 cada requisição à API:

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

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

Limites de chaves por plano

O número de chaves de API que você pode criar depende do seu plano:

Plano	Limite de chaves de API
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

Expiração da chave

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

Excluindo uma chave

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

Depois de excluída, a chave para de funcionar imediatamente. Qualquer aplicativo que use essa chave receberá erros de autenticação.