API de Credenciais

Crie e gerencie credenciais (assertions) — emblemas emitidos para destinatários específicos.

Todos os endpoints exigem autenticação por meio do cabeçalho X-Api-Key. Veja Autenticação.

Criar credencial

Emite um emblema para um destinatário.

Precisa emitir para centenas ou milhares de destinatários de uma só vez, em vez de uma chamada de API por pessoa? Use o recurso de interface Credenciais em massa, que aceita o upload de um CSV.

POST /awards

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
badgeId	string	Sim	O ID do emblema a ser emitido
recipient	object	Sim	Dados do destinatário (veja abaixo)
recipient.name	string	Sim	Nome completo do destinatário (mínimo de 5 caracteres)
recipient.email	string	Sim	Endereço de e-mail do destinatário
issuedOn	string	Sim	Data de emissão no formato ISO 8601 (ex.: 2025-01-15)
expires	string	Não	Data de expiração no formato ISO 8601

Exemplo

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

Resposta

{
  "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Observações

• Conta como uma credencial no seu pool anual de credenciais (Free: 1.200/ano, Starter: 12.000/ano, Pro: 120.000/ano). O pool é uma cota anual flexível — use quando quiser ao longo do ano, inclusive em picos — e é renovado no aniversário do cadastro da sua conta. A cobrança continua mensal; apenas a cota de credenciais é anual. Veja Planos e cobrança para mais detalhes.

---

Listar credenciais

Recupera credenciais com filtros e paginação opcionais.

GET /awards

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
filter	JSON string	Não	Objeto de filtro (veja abaixo)
lastEvaluatedKey	string	Não	Token de paginação de uma resposta anterior

Objeto de filtro

O parâmetro filter aceita uma string JSON com estes campos:

Campo	Tipo	Descrição
badgeId	string	Filtra por ID do emblema.
search	string	Trecho a ser procurado nos nomes ou e-mails dos destinatários (veja searchField).
searchField	string	name (padrão) ou email — qual coluna pesquisar.

A paginação via lastEvaluatedKey funciona com ou sem filtros. O tamanho da página é 50.

Exemplo — listar todas as credenciais

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

Exemplo — filtrar por emblema

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

Se lastEvaluatedKey estiver presente na resposta, há mais resultados. Passe-o como parâmetro de consulta na próxima requisição para obter a página seguinte.

---

Enviar e-mail da credencial

Envia ao destinatário uma notificação por e-mail sobre a credencial dele.

POST /awards/{awardId}/send

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	O ID da credencial (parâmetro de caminho e corpo)
email	string	Sim	Endereço de e-mail do destinatário

Exemplo

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

Resposta

Retorna uma string de confirmação simples:

"email sent"

---

Compartilhar credencial

Compartilha uma credencial por e-mail com vários destinatários.

POST /awards/{awardId}/share

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	O ID da credencial (parâmetro de caminho e corpo)
recipients	string	Sim	Lista de endereços de e-mail separados por vírgula
subject	string	Sim	Linha de assunto do e-mail
message	string	Sim	Corpo da mensagem do e-mail

Exemplo

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

Resposta

Retorna uma string de confirmação simples:

"email sent"

---

Revogar credencial

Revoga uma credencial que você emitiu. A assertion hospedada do Open Badges v2.0 é marcada com revoked: true (com um motivo opcional), de modo que qualquer verificador veja que o emblema não é mais válido. O registro da credencial é mantido para fins de auditoria, e nenhum crédito é reembolsado.

A revogação também se propaga para o Verifiable Credential do Open Badges 3.0 da credencial: o bit da credencial é alterado na W3C Bitstring Status List referenciada pelo credentialStatus do VC, para que as carteiras de VC também detectem a revogação. Veja Revogação (Bitstring Status List).

POST /awards/{awardId}/revoke

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	O ID da credencial (parâmetro de caminho)
reason	string	Não	Motivo da revogação. Truncado em 500 caracteres.
notify	boolean	Não	Quando true, envia um e-mail ao destinatário informando que a credencial foi revogada. O padrão é false.

Exemplo

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Resposta

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Revogar uma credencial já revogada é idempotente — retorna a mesma resposta sem reenviar a notificação.

Revogar em massa

Para revogar muitas credenciais de uma vez, use o endpoint durável de envio em massa com action: "revoke" em vez de chamar este endpoint para cada credencial:

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

Ele retorna { "jobId", "total" }; o job revoga cada ID no servidor (ignorando os já revogados) e pode ser retomado. IDs já revogados e inexistentes são informados como ignorados.

---

Excluir credencial

Exclui definitivamente uma credencial que você emitiu. Ao contrário da revogação, isso remove o registro por completo e a página pública da credencial passa a retornar 404. Use para erros genuínos (por exemplo, emitida para a pessoa errada); para credenciais reais, prefira revogar, para que a assertion continue verificável como revogada. Nenhum crédito é reembolsado.

DELETE /awards/{awardId}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
awardId	string	Sim	O ID da credencial (parâmetro de caminho)

Exemplo

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

Baixar certificado em PDF

Gera um certificado em PDF A4 pronto para impressão para uma credencial.

GET /certify-badge/award/{awardGuid}/pdf

Não exige autenticação — este endpoint é público para que os destinatários possam baixar o próprio certificado.

Exemplo

curl -OJ https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

A resposta é o PDF binário com o cabeçalho Content-Type: application/pdf.

---

Registrar evento da credencial

Registra um evento de engajamento. Usado pela página pública da credencial para alimentar as estatísticas de engajamento. Não exige autenticação.

POST /certify-badge/award/{awardGuid}/event

Parâmetros

Este endpoint lê o corpo diretamente (sem o wrapper parameters).

Parâmetro	Tipo	Obrigatório	Descrição
event	string	Sim	Um de view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Não	Quando event=share, a rede social: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Supressão de duplicatas por IP: o mesmo evento vindo do mesmo IP é contado uma vez a cada 24 horas.

Exemplo

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

Resposta

{
  "ok": true
}

---

Obter estatísticas da credencial

Recupera os contadores cumulativos de engajamento de uma credencial.

GET /certify-badge/award/{awardGuid}/stats

Não exige autenticação.

Resposta

Os contadores são retornados indexados pelo tipo bruto do evento. totals contém a contagem total por evento; networks detalha a divisão por rede dos eventos que carregam um network (atualmente share). Eventos sem atividade registrada simplesmente não aparecem.

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}