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

A revogação nos Open Badges: como funciona, o que muda para o destinatário e a forma certa de tratar «emitido por engano», «credencial expirada» e «violação de política».

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

Mais cedo ou mais tarde, todos os programas que emitem credenciais digitais têm de retirar uma. Um certificado foi para a pessoa errada. Descobriu-se que um formando copiou no exame final. Um contrato com um parceiro terminou e os emblemas que diziam «Certified Partner» já não devem ser válidos. Emitir é o caminho feliz; a revogação é a parte que decide se as tuas credenciais merecem mesmo confiança.

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

O que significa «revogar» nos Open Badges

Na especificação Open Badges v2.0, cada emblema emitido é uma assertion (declaração): um pequeno documento JSON-LD alojado num URL público que diz «este emissor atribuiu este emblema a este destinatário nesta data». A revogação é simplesmente uma alteração a esse documento alojado. A assertion passa a ter "revoked": true e, opcionalmente, uma cadeia "revocationReason" a explicar o motivo.

Este desenho tem uma consequência importante que surpreende muitos responsáveis de programas:

  • A assertion alojada é a fonte de verdade. Quem verifica a credencial obtendo o URL da assertion ou abrindo a página de verificação vê imediatamente o estado revogado.
  • As cópias não são recolhidas. Se o destinatário descarregou a imagem do emblema ou o JSON, ou o fixou num portefólio, esse ficheiro não muda. Continua a conter uma ligação para a tua assertion alojada, pelo que um verificador que siga a ligação verá que está revogada, mas quem olhar de relance para um PNG guardado não verá.

A revogação é, portanto, uma declaração feita no ponto de verificação, não uma eliminação. Pensa nela como carimbar «VOID» no registo principal em vez de ir atrás de cada fotocópia.

Se quiseres ver o próprio documento mais de perto, o nosso guia do JSON-LD de um Open Badge percorre cada campo.

Revogar, reemitir ou eliminar: escolhe a ação certa

Antes de clicares em qualquer coisa, decide qual das três ações se adequa à situação. Não são intermutáveis.

SituaçãoMelhor açãoPorquê
A credencial foi emitida à pessoa errada ou com um erro de escritaEliminar (se nunca foi enviada) ou Revogar e depois reemitirEliminar remove o registo por completo; revogar mantém um rasto de auditoria
O formando violou uma política ou a credencial foi obtida de forma indevidaRevogar, com um motivoO registo continua verificável como revogado, que é o que queres numa disputa
A credencial limitou-se a atingir a data de fimNão fazer nada; define uma validade ao emitirA expiração é um evento normal do ciclo de vida, não uma revogação
Programa cancelado, turma anuladaRevogação em massaUma tarefa, um motivo, aplicado a todos
Os dados estavam errados mas a credencial é válidaEditar antes de enviar, ou revogar e reemitir depois de enviadaMantém a experiência do destinatário limpa

Duas regras práticas:

  1. Prefere revogar a eliminar em tudo o que seja real. A página pública de uma credencial eliminada devolve um erro de «não encontrado». Uma revogada continua a resolver e diz claramente que está revogada, o que é uma prova muito melhor se alguém perguntar mais tarde o que aconteceu.
  2. Nunca uses a revogação como substituto da expiração. Se uma credencial só é válida durante dois anos, define uma data de validade ao emiti-la. Um emblema que caduca discretamente é diferente de um que foi retirado, e a tua página de verificação deve dizer qual dos casos é.

Revogar a partir do painel

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

  1. Inicia sessão e abre Awards na barra lateral.
  2. Encontra a credencial. A lista mostra o destinatário, o nome do emblema, a data de emissão e a validade, e podes pesquisar por destinatário.
  3. Clica na linha (ou em View) para abrir o modal de detalhe da credencial.
  4. Clica em Revoke.
  5. Na caixa de diálogo de confirmação, introduz opcionalmente um motivo e, se quiseres, assinala Email the recipient that their credential was revoked.
  6. Confirma.

Award detail modal

A credencial permanece na tua lista com uma etiqueta vermelha Revoked junto ao destinatário, para que tu e a tua equipa possam sempre ver o que foi retirado. Revogar não devolve a credencial à quota do teu plano. Emitiste-a, contou.

Uma nota sobre o campo do motivo

O motivo é opcional, mas preenche-o. É guardado com a credencial, aparece como revocationReason na assertion pública dos Open Badges e é incluído no payload do webhook que os teus sistemas recebem. Como é público na assertion, escreve-o a pensar num leitor externo. «Emitido por engano» ou «Programa cancelado» está bem. «A Joana copiou na pergunta 14» não está. Guarda os detalhes pessoais nos teus próprios registos e mantém o motivo público neutro.

Deves enviar um email ao destinatário?

Normalmente, sim. Um formando que só descobre que a credencial deixou de valer quando um empregador clica na ligação de verificação tem todo o direito de ficar descontente contigo. A notificação é opcional precisamente porque algumas revogações (uma limpeza em massa de atribuições de teste, por exemplo) não precisam de incomodar ninguém. A nossa recomendação:

  • Envia email quando a revogação afeta uma pessoa real que ainda possa estar a exibir a credencial.
  • Não envies email quando estiveres a arrumar dados de teste internos ou a anular credenciais que nunca foram enviadas.

Revogar muitas credenciais de uma vez

Os programas raramente precisam de revogar uma credencial isolada; o mais comum é uma turma inteira. Na lista de Awards:

  1. Assinala as caixas das credenciais que queres retirar.
  2. Clica em Revoke selected na barra de ações em massa.
  3. Adiciona um motivo, decide se notificas os destinatários e confirma.

A revogação em massa corre como uma tarefa durável em segundo plano, por isso umas centenas de credenciais não farão o separador do browser expirar. As credenciais já revogadas são ignoradas em vez de fazerem falhar o lote, e uma tarefa interrompida a meio pode ser retomada. O mesmo mecanismo alimenta a emissão em massa a partir de uma folha de cálculo, que abordamos em como emitir Open Badges a partir de um CSV.

Revogar através da API

Se o teu sistema de aprendizagem ou plataforma de RH decide quem deixou de estar certificado, podes revogar por programação. 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 devolve a mesma resposta de sucesso e não envia uma segunda notificação. Isso torna-a segura para chamar a partir de uma tarefa com repetições.
  • Os motivos são truncados em 500 caracteres.
  • notify é false por omissão. Nada é enviado por email a menos que o peças.
  • A revogação em massa está disponível através do endpoint de operações em massa com action: "revoke" e uma lista de IDs de awards; devolve um ID de tarefa que podes acompanhar. Os parâmetros completos estão na referência da API de awards.

Só precisas da API quando a revogação é conduzida por outro sistema. Para um caso pontual, o painel é mais rápido e tem um passo de confirmação que te protege de um ID mal escrito.

O que veem o destinatário e o verificador

Depois de revogares, eis 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 partilha social recebe o prefixo «[Revoked]», para que uma ligação partilhada não pareça uma credencial ativa num cartão de pré-visualização.

Na assertion Open Badges v2.0. O JSON alojado em https://api.badges.ninja/certify-badge/award/<award-id> passa a incluir "revoked": true, mais "revocationReason" se indicaste um motivo. As assertions revogadas ficam em cache apenas cerca de 30 segundos, ao passo que as ativas ficam cinco minutos, pelo que a alteração chega rapidamente aos verificadores.

Na credencial Open Badges 3.0. A revogação também inverte o bit da credencial numa W3C Bitstring Status List, que é como as carteiras de credenciais verificáveis e os verificadores a detetam. Essa lista fica em cache por pouco tempo, por isso conta com uma propagação em cerca de um minuto. Se estás a ponderar as duas versões, vê Open Badges v2 vs v3.

Na cópia do próprio destinatário. Nada muda no ficheiro que descarregou. A imagem do emblema no portátil dele tem exatamente o mesmo aspeto. O que muda é o resultado da verificação: quem clicar na ligação ou verificar a credencial por programação obtém a resposta de revogada. Se o notificaste, também tem um email a explicar porquê.

No LinkedIn. Uma credencial adicionada a um perfil do LinkedIn é uma ligação mais metadados que apontam para a tua página de verificação. O LinkedIn não consulta periodicamente a revogação por ti, pelo que a entrada pode permanecer no perfil, mas quem seguir a ligação chega à página de revogada. É mais uma razão para enviares a notificação e pedires ao destinatário que remova a entrada.

Avisa os teus próprios sistemas: webhooks

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

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

Subscreve-o e os teus sistemas a jusante mantêm-se sincronizados sem que ninguém tenha de se lembrar de os atualizar. Os detalhes de configuração estão na documentação de webhooks, e o modelo de eventos mais alargado é abordado em configuração de webhooks para eventos de emblemas.

Uma política de revogação simples que podes adotar hoje

As ferramentas são a parte fácil. A parte mais difícil é decidir de antemão quando vais revogar e quem pode fazê-lo. Uma política escrita e curta evita discussões mais tarde. Um modelo viável:

  1. Motivos de revogação. Lista-os: emitida por engano, obtida através de má conduta, requisito deixou de ser cumprido (por exemplo, uma subscrição caducou) ou programa retirado.
  2. Quem decide. Indica uma função, não uma pessoa. Limita a permissão de revogar a essa função.
  3. Aviso. Indica que os destinatários são informados por email, 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 diz em quanto tempo vais responder. Se um recurso tiver sucesso, reemite uma credencial nova em vez de tentares desfazer a revogação, e o histórico mantém-se limpo.
  5. Registo. Mantém uma nota interna de quem revogou o quê e porquê, separada do motivo público neutro.

Publica a política na mesma página onde descreves a credencial, para que os formandos conheçam as regras antes de se inscreverem.

Erros comuns a evitar

  • Eliminar quando querias revogar. Eliminar é permanente, não pode ser desfeito e faz a página pública desaparecer. Usa-o para erros genuínos em credenciais que ninguém viu.
  • Pôr detalhes privados no motivo. É público na assertion.
  • Esperar que as cópias guardadas mudem. A revogação vive no ponto de verificação. Diz aos destinatários que removam a credencial dos perfis e portefólios.
  • Revogar em vez de expirar. Usa uma data de validade para credenciais com prazo limitado.
  • Presumir um reembolso. As credenciais revogadas continuam a contar para a quota do teu plano.
  • Esquecer os sistemas a jusante. Liga o webhook para que os acessos e registos acompanhem o estado da credencial.

Perguntas frequentes

Posso anular uma revogação? Não através da interface. Se revogaste por engano, emite uma nova credencial ao destinatário. A revogada permanece como parte do rasto de auditoria.

O destinatário tem de fazer alguma coisa? Não. Se escolheste notificá-lo, recebe um email. Caso contrário, a alteração 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, possas preferir editá-la antes de enviar, ou eliminá-la se ninguém a viu.

Há um limite para quantas posso revogar? A revogação em massa corre como uma tarefa retomável em segundo plano, por isso lotes grandes são tratados numa só operação em vez de um a um.

Os empregadores vão ver que uma credencial foi revogada? Quem a verificar através do URL público ou da assertion vê o estado de revogada e o motivo, se o tiveres indicado.

Conclusão

Revogar um Open Badge é uma ação pequena com consequências reais para a confiança. Faz isso a partir do painel quando for uma única credencial, usa a revogação em massa para uma turma e recorre à API ou aos webhooks quando outro sistema é dono da decisão. Mantém os motivos neutros, notifica quem precisa de saber e lembra-te de que a revogação muda o que os verificadores veem, não os ficheiros que já estão nas mãos dos destinatários.

Pronto para emitir a tua primeira credencial verificável? Começa 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