Chaves de API

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

Criar uma chave de API

1. Abra a página Chaves de API na barra lateral.
2. Clique em Criar chave de API. Abre-se um formulário em linha:

3. Atribua um nome à chave e clique em Criar. A chave completa é revelada apenas uma vez num banner verde:

4. Copie a chave imediatamente — a chave completa é mostrada uma única vez. Se a perder, terá de criar uma nova. Após fechar o banner, o painel passa a mostrar apenas o prefixo da chave (por exemplo, bws_a1b2c3d4...); a chave completa fica guardada no servidor para autenticar os seus pedidos:

Cada linha mostra também quando a chave foi criada e, depois de ter sido utilizada, uma data de última utilização, para que possa identificar chaves obsoletas.

Âmbitos de acesso

Ao criar uma chave, pode torná-la só de leitura ou deixá-la com acesso completo:

Âmbito	Permite
Acesso completo (predefinição)	Leitura e escrita — listar dados e criar, emitir, atualizar ou eliminar.
Só de leitura	Apenas pedidos GET seguros. Qualquer pedido que altere dados (POST, PUT, PATCH, DELETE) é rejeitado com 403 Forbidden.

Utilize uma chave só de leitura para integrações que precisam apenas de ler os seus dados (relatórios, painéis, cópias de segurança), de modo que uma chave divulgada não possa alterar nada. Assinale Chave só de leitura no formulário de criação; as chaves só de leitura mostram um selo Só de leitura na lista. As chaves criadas antes de os âmbitos existirem mantêm o acesso completo.

Formato das chaves

As chaves de API utilizam o prefixo bws_ seguido de uma cadeia hexadecimal de 32 caracteres:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Utilizar chaves de API nos pedidos

Inclua a chave de API no cabeçalho X-Api-Key em cada pedido feito à API:

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

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

Limites de chaves por plano

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

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

Expiração das chaves

Cada chave de API expira um ano após a sua criação. Assim que uma chave expira, deixa de autenticar pedidos, exactamente como se tivesse sido eliminada. Crie uma nova chave antes de a antiga caducar para evitar interrupções.

Eliminar uma chave

1. Abra a página Chaves de API.
2. Localize a chave que pretende eliminar.
3. Clique em Eliminar.
4. Confirme a eliminação.

Após ser eliminada, a chave deixa imediatamente de funcionar. Quaisquer aplicações que estejam a utilizá-la irão receber erros de autenticação.