Como revogar um Open Badge (e o que acontece com a cópia do destinatário)

Revogação em Open Badges: como funciona, o que muda para o destinatário e a forma certa de lidar com «emitido por engano» versus «credencial expirada» versus «violação de política».

Nacho Coll Por Atualizado 11 min de leitura
Revogação em Open Badges: como funciona, o que muda para o destinatário e a forma certa de lidar com «emitido por engano» versus «credencial expirada» versus «violação de política».

Mais cedo ou mais tarde, todo programa que emite credenciais digitais precisa retirar alguma. Um certificado foi para a pessoa errada. Descobriu-se que um aluno colou na avaliação final. O contrato com um parceiro acabou e os emblemas que diziam «Certified Partner» não deveriam mais ser válidos. Emitir é o caminho feliz; revogar é o que decide se suas credenciais são realmente confiáveis.

Este guia explica como a revogação funciona em Open Badges, o que o destinatário vê e não vê depois, e como revogar uma credencial ou algumas centenas em https://badges.ninja, pelo painel ou pela API.

O que significa «revogar» em Open Badges

Na especificação Open Badges v2.0, todo emblema emitido é uma asserção (assertion): um pequeno documento JSON-LD hospedado em uma URL pública que diz «este emissor concedeu este emblema a este destinatário nesta data». Revogar é simplesmente uma mudança nesse documento hospedado. A asserção passa a ter "revoked": true e, opcionalmente, uma string "revocationReason" explicando o motivo.

Esse desenho tem uma consequência importante que surpreende muitos responsáveis por programas:

  • A asserção hospedada é a fonte da verdade. Qualquer pessoa que verifique a credencial buscando a URL da asserção ou abrindo a página de verificação vê o estado de revogada imediatamente.
  • As cópias não são recolhidas. Se o destinatário baixou a imagem do emblema ou o JSON, ou o fixou em um portfólio, esse arquivo não muda. Ele ainda contém um link para a sua asserção hospedada, então um verificador que seguir o link verá que ela está revogada, mas quem apenas olha para um PNG salvo não perceberá.

A revogação, portanto, é uma declaração feita no ponto de verificação, não uma exclusão. Pense nisso como carimbar «NULO» no registro mestre, em vez de correr atrás de cada fotocópia.

Se quiser ver o documento de perto, nosso passo a passo do JSON-LD de um Open Badge percorre cada campo.

Revogar, reemitir ou excluir: escolha a ação certa

Antes de clicar em qualquer coisa, decida qual das três ações se encaixa na situação. Elas não são intercambiáveis.

SituaçãoMelhor açãoPor quê
A credencial foi emitida para a pessoa errada ou com um erro de digitaçãoExcluir (se nunca foi enviada) ou Revogar e depois reemitirExcluir remove o registro por completo; revogar mantém uma trilha de auditoria
O aluno violou uma política ou a credencial foi obtida de forma indevidaRevogar, com um motivoO registro continua verificável como revogado, que é exatamente o que você quer numa disputa
A credencial simplesmente chegou à data de términoNão faça nada; defina uma validade ao emitirA expiração é um evento normal do ciclo de vida, não uma revogação
Programa cancelado, turma anuladaRevogação em massaUm trabalho, um motivo, aplicado a todos
Os dados estavam errados, mas a credencial é válidaEditar antes de enviar, ou revogar e reemitir depois de enviarMantém limpa a experiência do destinatário

Duas regras práticas:

  1. Prefira revogar a excluir para qualquer coisa real. A página pública de uma credencial excluída retorna um erro de «não encontrada». Uma revogada continua resolvendo e diz claramente que foi revogada, o que é uma evidência muito melhor se alguém perguntar depois o que aconteceu.
  2. Nunca use a revogação como substituto da expiração. Se uma credencial só vale por dois anos, defina uma data de validade ao emiti-la. Um emblema que expira silenciosamente é diferente de um que foi retirado, e sua página de verificação deve dizer qual é o caso.

Revogando pelo painel

Para um punhado de credenciais, o painel é o caminho mais rápido e não exige código.

  1. Entre na sua conta e abra Awards na barra lateral.
  2. Encontre a credencial. A lista mostra o destinatário, o nome do emblema, a data de emissão e a validade, e você pode buscar por destinatário.
  3. Clique na linha (ou em View) para abrir o modal de detalhes da credencial.
  4. Clique em Revoke.
  5. Na caixa de confirmação, informe opcionalmente um motivo e, também opcionalmente, marque Email the recipient that their credential was revoked.
  6. Confirme.

Award detail modal

A credencial permanece na sua lista com uma etiqueta vermelha Revoked ao lado do destinatário, para que você e sua equipe sempre vejam o que foi retirado. Revogar não devolve a credencial à cota do seu plano. Você a emitiu, e ela contou.

Uma observação sobre o campo de motivo

O motivo é opcional, mas preencha. Ele é armazenado com a credencial, aparece como revocationReason na asserção pública do Open Badges e é incluído no payload do webhook que seus sistemas recebem. Como é público na asserção, escreva pensando em um leitor externo. «Emitida por engano» ou «Programa cancelado» está ótimo. «Jane colou na questão 14» não. Mantenha os detalhes pessoais nos seus próprios registros e deixe o motivo público neutro.

Você deve avisar o destinatário por e-mail?

Normalmente, sim. Um aluno que só descobre que sua credencial perdeu a validade quando um empregador clica no link de verificação tem todo o direito de ficar chateado com você. A notificação é opcional justamente porque algumas revogações (uma limpeza em massa de credenciais de teste, por exemplo) não precisam incomodar ninguém. Nossa orientação:

  • Envie o e-mail quando a revogação afetar uma pessoa real que ainda possa estar exibindo a credencial.
  • Pule o e-mail quando você estiver organizando dados internos de teste ou anulando credenciais que nunca foram enviadas.

Revogando muitas credenciais de uma vez

Um programa raramente precisa revogar uma credencial isolada; o mais comum é uma turma inteira. Na lista de Awards:

  1. Marque as caixas das credenciais que você quer retirar.
  2. Clique em Revoke selected na barra de ações em massa.
  3. Adicione um motivo, decida se vai notificar os destinatários e confirme.

A revogação em massa roda como um job durável em segundo plano, então algumas centenas de credenciais não vão estourar o tempo limite da aba do seu navegador. Credenciais que já estão revogadas são ignoradas em vez de fazer o lote falhar, e um job interrompido no meio pode ser retomado. A mesma estrutura sustenta a emissão em massa a partir de uma planilha, que explicamos em como emitir Open Badges a partir de um CSV.

Revogando pela API

Se o seu sistema de aprendizagem ou a plataforma de RH decide quem deixa de ser certificado, você pode revogar de forma programática. O endpoint é POST /awards/{awardId}/revoke, autenticado com uma chave de API (X-Api-Key: bws_<32-hex>) ou um token Bearer do Cognito. O ID do award vai no caminho; reason e notify vão no corpo JSON e ambos são opcionais.

Com curl:

curl -X POST https://api.badges.ninja/awards/<award-id>/revoke \
  -H "X-Api-Key: bws_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Issued to the wrong recipient","notify":true}'
# 200 -> {"revoked":true,"awardId":"<award-id>"}

Em JavaScript:

const res = await fetch(`https://api.badges.ninja/awards/${awardId}/revoke`, {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ reason: "Program cancelled", notify: false }),
});
const { revoked } = await res.json(); // true

E em Python:

import requests
res = requests.post(
    f"https://api.badges.ninja/awards/{award_id}/revoke",
    headers={"X-Api-Key": API_KEY},
    json={"reason": "Program cancelled", "notify": False},
)
print(res.json()["revoked"])  # True

Alguns detalhes práticos que vale a pena conhecer:

  • É idempotente. Revogar uma credencial que já está revogada retorna a mesma resposta de sucesso e não envia uma segunda notificação. Isso a torna segura para ser chamada por um job com novas tentativas.
  • Os motivos são truncados em 500 caracteres.
  • notify é false por padrão. Nada é enviado por e-mail a menos que você peça.
  • A revogação em massa está disponível pelo endpoint em massa com action: "revoke" e uma lista de IDs de awards; ele retorna um ID de job que você pode acompanhar. Os parâmetros completos estão na referência da API de awards.

Você só precisa da API quando a revogação é disparada por outro sistema. Para um caso pontual, o painel é mais rápido e tem uma etapa de confirmação que protege você de um ID digitado errado.

O que o destinatário e o verificador veem

Depois de revogar, veja o que muda e com que rapidez.

Na página pública de verificação. A página em https://badges.ninja/awards/<award-id> mostra a credencial como revogada, e o título da página para compartilhamento social recebe o prefixo «[Revoked]», para que um link compartilhado não pareça uma credencial ativa em um cartão de pré-visualização.

Na asserção Open Badges v2.0. O JSON hospedado em https://api.badges.ninja/certify-badge/award/<award-id> agora traz "revoked": true, além de "revocationReason" se você informou um. Asserções revogadas ficam em cache por apenas cerca de 30 segundos, enquanto as ativas ficam por cinco minutos, então a mudança chega rápido aos verificadores.

Na credencial Open Badges 3.0. A revogação também aciona o bit da credencial em uma W3C Bitstring Status List, que é como as carteiras e os verificadores de credenciais verificáveis a detectam. Essa lista fica em cache por pouco tempo, então espere uma propagação de cerca de um minuto. Se você está avaliando as duas versões, veja Open Badges v2 vs v3.

Na cópia do próprio destinatário. Nada muda no arquivo que ele baixou. A imagem do emblema no notebook dele continua idêntica. O que muda é o resultado da verificação: quem clicar no link ou checar a credencial de forma programática recebe a resposta de revogada. Se você o notificou, ele também tem um e-mail explicando o motivo.

No LinkedIn. Uma credencial adicionada a um perfil do LinkedIn é um link mais metadados que aponta de volta para a sua página de verificação. O LinkedIn não consulta a revogação por você, então a entrada pode continuar no perfil, mas quem seguir o link cai na página de revogada. É mais um motivo para enviar a notificação e pedir ao destinatário que remova a entrada.

Avise seus próprios sistemas: webhooks

A revogação raramente é o fim da história dentro da sua organização. O aluno pode precisar perder o acesso a uma comunidade, um registro de empregador pode precisar ser atualizado ou uma tag do CRM precisa ser removida. O Badges Ninja emite um evento de webhook credential.revoked quando uma credencial é revogada, com a URL do award e o motivo:

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<award-id>",
  "reason": "Issued in error"
}

Assine o evento e seus sistemas a jusante ficam em sincronia sem que ninguém precise lembrar de atualizá-los. Os detalhes de configuração estão na documentação de webhooks, e o modelo de eventos mais amplo é tratado em configuração de webhooks para eventos de emblemas.

Uma política de revogação simples que você pode adotar hoje

As ferramentas são a metade fácil. A metade difícil é decidir com antecedência quando você vai revogar e quem pode fazê-lo. Uma política curta e por escrito evita discussões depois. Um modelo que funciona:

  1. Motivos para revogação. Liste-os: emitida por engano, obtida por má conduta, requisito que deixou de ser cumprido (por exemplo, uma associação que expirou) ou programa encerrado.
  2. Quem decide. Nomeie um papel, não uma pessoa. Limite a permissão de revogar a esse papel.
  3. Aviso. Informe que os destinatários são avisados por e-mail, com o motivo, a menos que a credencial nunca tenha sido entregue.
  4. Recurso. Dê aos destinatários uma forma de contestar a decisão e diga em quanto tempo você responderá. Se um recurso for aceito, reemita uma credencial nova em vez de tentar desfazer a revogação, e o histórico fica limpo.
  5. Registro. Mantenha uma nota interna de quem revogou o quê e por quê, separada do motivo público neutro.

Publique a política na mesma página em que você descreve a credencial, para que quem a conquista conheça as regras antes de se inscrever.

Erros comuns a evitar

  • Excluir quando você queria revogar. Excluir é permanente, não pode ser desfeito e faz a página pública desaparecer. Use para erros genuínos em credenciais que ninguém viu.
  • Colocar detalhes privados no motivo. Ele é público na asserção.
  • Esperar que as cópias salvas mudem. A revogação vive no ponto de verificação. Diga aos destinatários que removam a credencial de perfis e portfólios.
  • Revogar em vez de expirar. Use uma data de validade para credenciais com prazo limitado.
  • Presumir um reembolso. Credenciais revogadas continuam contando na cota do seu plano.
  • Esquecer os sistemas a jusante. Configure o webhook para que acessos e registros acompanhem o status da credencial.

Perguntas frequentes

Posso desfazer uma revogação? Não pela interface. Se você revogou por engano, emita uma nova credencial ao destinatário. A revogada permanece como parte da trilha de auditoria.

O destinatário precisa fazer alguma coisa? Não. Se você optou por notificá-lo, ele recebe um e-mail. Caso contrário, a mudança acontece silenciosamente na página de verificação.

A revogação funciona para credenciais que nunca foram enviadas? Sim, embora, para uma credencial não enviada com um erro simples, você possa preferir editá-la antes de enviar ou excluí-la se ninguém a viu.

Existe um limite de quantas posso revogar? A revogação em massa roda como um job retomável em segundo plano, então lotes grandes são tratados em uma única operação em vez de uma por uma.

Os empregadores vão ver que uma credencial foi revogada? Qualquer pessoa que a verifique pela URL pública ou pela asserção vê o status de revogada e o motivo, se você informou um.

Conclusão

Revogar um Open Badge é uma ação pequena com consequências reais para a confiança. Faça pelo painel quando for uma única credencial, use a revogação em massa para uma turma e recorra à API ou aos webhooks quando outro sistema for o dono da decisão. Mantenha os motivos neutros, avise quem precisa saber e lembre-se de que a revogação muda o que os verificadores veem, não os arquivos que já estão nas mãos dos destinatários.

Pronto para emitir sua primeira credencial verificável? Comece grátis em badges.ninja: designer visual, página pública de verificação, certificado em PDF, saída Open Badge v2.0. Sem cartão de crédito.

Nacho Coll

Sobre o autor

Founder & Engineer at Badges Ninja

Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.

Voltar ao Blog

Artigos Relacionados