Chaves de API

As chaves de API permitem aceder à API REST do badges.ninja de forma programática. Utilize-as para automatizar a criação, a emissão e a gestão de emblemas 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. É aberto um formulário em linha:

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

4. Copie a chave de imediato — a chave completa só é apresentada uma vez. Se a perder, terá de criar uma nova. Depois de fechar o banner, o painel mostra 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 utilizada, um carimbo de data/hora de última utilização, para que possa identificar chaves em desuso.

Âmbitos de acesso

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

Âmbito	Permite
Acesso total (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 em integrações que apenas precisam de ler os seus dados (relatórios, painéis, cópias de segurança), para que a fuga de uma chave não permita alterar nada. Assinale Chave só de leitura no formulário de criação; as chaves só de leitura apresentam um selo Só de leitura na lista. As chaves criadas antes de existirem âmbitos mantêm o acesso total.

Formato da chave

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

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Utilizar chaves de API nos pedidos

Inclua a chave de API no cabeçalho X-Api-Key de cada pedido à 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 obter todos os detalhes sobre a autenticação na 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/mo)	5
Pro ($29/mo)	20

Expiração da chave

Todas as chaves de API expiram um ano após a criação. Quando uma chave expira, deixa de autenticar pedidos, exatamente 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.

Depois de eliminada, a chave deixa de funcionar de imediato. Todas as aplicações que utilizem essa chave receberão erros de autenticação.