Autenticação

Todas as requisições à API do badges.ninja exigem autenticação. Esta página explica como autenticar suas requisições.

URL base

https://api.badges.ninja

Todos os endpoints da API são relativos a esta URL base.

Autenticação por chave de API

O principal método de autenticação é uma chave de API passada no cabeçalho X-Api-Key.

Obtendo uma chave de API

Pelo painel:

1. Entre em badges.ninja.
2. Acesse Chaves de API na barra lateral.
3. Clique em Criar chave de API.
4. Copie a chave (ela só é exibida uma vez).

Pela API:

As chaves de API também podem ser gerenciadas pela API usando seu token JWT do fluxo de autenticação Cognito. Consulte o painel para a abordagem mais simples.

Usando sua chave de API

Inclua o cabeçalho X-Api-Key em toda requisição:

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

Formato da chave de API

As chaves usam o prefixo bws_:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Formato de requisição

• Requisições GET passam parâmetros como query strings
• Requisições POST e PUT enviam um corpo JSON com um objeto parameters
• Todas as respostas retornam JSON com Content-Type: application/json

Estrutura de requisição POST/PUT

{
  "parameters": {
    "name": "Meu distintivo",
    "description": "Um distintivo de exemplo"
  }
}

Exemplo de requisição

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Minha organização",
      "url": "https://example.com",
      "email": "admin@example.com"
    }
  }'

Exemplo de resposta

{
  "statusCode": 200,
  "info": {
    "issuerId": "https://api.badges.ninja/certify-badge/issuer/abc123-def456"
  }
}

Limites de taxa

As requisições à API estão sujeitas a limitação de taxa. Se você exceder o limite, recebe uma resposta 429 Too Many Requests. Aguarde alguns segundos e tente novamente.

Endpoints públicos

Alguns endpoints não exigem autenticação. São os endpoints públicos de verificação em /certify-badge/ que permitem a qualquer pessoa verificar as credenciais de um distintivo.