Concepts

The domain vocabulary of Open API v2. All of these are standard Kolleges domain terms.

Core resources

Term	Meaning
club	The entity that runs classes and issues credentials. Identified by clubDomain (in the path).
apiClient	The credential unit issued in the dashboard. Bound to one club and carries least-privilege scopes.
achievement	A reusable issuance template/form (e.g. “2026 Certificate of Completion”).
design	The visual design of the certificate or badge attached to an achievement.
issuance	One issued credential (= a certificate/badge issued to a single person).
holder	The recipient subject of a credential. A PII-free anchor (did:key), separate from the recipient’s personal data.
credential (VC)	The permanent, verifiable form of an issuance — Open Badges 3.0 / W3C VC, did:key · VC-JWT.

Permanence invariant

An issued VC survives as verifiable even if its user, club, or issuance record is deleted. The credential is anchored to a PII-free holder (did:key), and the recipient’s personal data can be erased separately.

Response envelope

Every successful response takes one of three shapes.

// Single
{ "data": { /* resource */ } }

// Cursor-paginated list
{ "data": [ /* … */ ], "meta": { "nextCursor": "…" | null } }

// Issuance batch (BatchResultDto) — always HTTP 200
{
  "results": [
    { "ref": "u-42", "status": "issued", "resourceId": 456 },
    { "ref": "u-43", "status": "skipped", "error": null },
    { "ref": "u-44", "status": "failed", "error": { "code": "…", "detail": "…" } }
  ],
  "summary": { "total": 3, "ok": 1, "skipped": 1, "failed": 1 }
}

A single issuance is just an array of one

The issuance endpoint is the same whether single or batch — just put one item in the recipients array. The response is always a BatchResultDto (with a per-recipient ref key), which cleanly distinguishes partial failures.

Idempotency

Write requests such as issuance require the Idempotency-Key header. Retrying with the same key returns the original result unchanged instead of issuing again — so you can retry safely on network failure. Scope the key to a logical unit of work (e.g. an order number).

Revocation = invalidation

Revoking an issuance is a revocation. The issued VC itself is preserved forever, but its status changes to revoked and it is shown as invalid on verification. It’s a state transition, not a hard delete.

Evolution policy

Response enums may evolve additively — handle unknown enum values leniently (don’t fail on values you don’t recognize). New fields may be added, but existing fields are kept.