Documentation

Evidence

Links, files and notes on a credential — and why what a recipient submits is moderated.

A credential says somebody achieved something. Evidence is the supporting material: the project they built, the transcript behind the grade, an examiner's note.

Three kinds

Kind What it is Where the content lives
LINK An http(s) URL to something hosted elsewhere url
FILE A file uploaded here, served by signed URL storageKey
NOTE Text typed by a person note

Each row carries exactly one of the three. A LINK that also sent a note is refused rather than stored: if two content fields were set, a reader could not tell which was authoritative.

Attaching evidence as the issuer

curl -X POST https://api.example.com/api/org/credentials/$ID/evidence \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"LINK","label":"Project repository","url":"https://github.com/example/work"}'

A file is a two-step upload, so the bytes never pass through the API:

# 1. Ask for a presigned PUT. The key is built server-side; you never choose it.
curl -X POST .../credentials/$ID/evidence/presign \
  -d '{"fileName":"transcript.pdf","contentType":"application/pdf","size":182344}'

# 2. PUT the bytes to the returned uploadUrl, then attach by key.
curl -X POST .../credentials/$ID/evidence \
  -d '{"kind":"FILE","label":"Transcript","storageKey":"<key>","fileName":"transcript.pdf","contentType":"application/pdf"}'

The size is re-read from the bucket, not taken from your request. The browser uploaded the bytes directly, so what a client claims it sent and what is actually there are two different facts, and this is the first moment the server can check. An object that is missing means the upload never completed, which is a better error now than a broken download later.

Evidence a recipient submits is moderated

A recipient can attach evidence to their own credential, through the same private link they use to accept an offer. It lands PENDING, shows nowhere public, and waits for a decision from somebody holding evidence:moderate.

This is not friction for its own sake. A credential is the issuer's statement. If the person it is about could append arbitrary text and files to the public record, the issuer would be vouching for words they never wrote — on a page that exists precisely so a stranger can decide whether to believe the issuer.

A rejection is never published. Whether something was turned down is between the issuer and the recipient; telling a reader that the holder tried to add something the institution refused would be worse than saying nothing.

Evidence is outside the signature

This is the part worth reading twice.

Credential.proof is signed once, at publish, and served unchanged. The Open Badges 3.0 document therefore carries a snapshot of the approved, public evidence frozen at that moment — not a live read.

So:

  • Evidence attached before publish is inside the signed document.
  • Evidence attached after publish appears on the check page and in the API, and not inside the signed document. The API tells you which happened: the response to an add carries inSignedDocument.
  • To get new evidence inside the signature, correct the credential. A correction issues a replacement, which is signed afresh.

The alternative — reading evidence live — would mean a document that stopped matching its own stored signature the first time anybody attached a file. A verifier who had already fetched and checked the credential would find it invalid, with nothing to explain why.

Bounds

Limit Value Why
Pieces per credential 20 Enough for a portfolio, not enough to be a file host
Pending recipient submissions 5 A moderation queue, not an inbox
File size 10 MB Refused, never truncated
Note length 4,000
Link length 2,000

A link must be absolute http or https. Any other scheme is refused — javascript: and data: URLs are rendered on the public check page as links, and the check page is the one surface in this product that an unauthenticated stranger loads.

Permissions and plan

evidence:view, evidence:manage (attach and edit) and evidence:moderate (decide on a recipient's submission) are separate. The built-in Issuer role can attach but not moderate; the Approver role can moderate but not attach. Deciding whether an organisation endorses somebody's own account of themselves is the same kind of judgement as deciding whether to publish, and belongs with the same people.

Evidence needs the evidence plan feature; recipient submission needs recipientEvidence.