Quickstart

A getting-started guide for direct customers (the data controller of their own club) who want to automate Kolleges via API. The canonical contract = the Open API v2 reference. If you’re a channel partner operating multiple clubs on others’ behalf, see the separate Partner API reference (host partner.kolleges.net). If you only need to verify or read back issued credentials (verifiers, wallets, an LMS), use the unauthenticated Open Badges 3.0 public verification reference (host api.kolleges.net) — the signed VC-JWT is the only frozen record, and the criteria, skills and engraved description are read from it.

Concepts at a glance

• API client (apiClient) = the credential unit you issue in the dashboard. Bound to exactly one club.
• Authentication = OAuth2 client_credentials. No long-lived static keys — exchange your client_secret for a 15-minute ES256 token and use that.
• Surface = https://openapi.kolleges.net/v2/clubs/{clubDomain}/…. clubDomain lives in the path only (one exception: GET /v2/me, the bootstrap route that tells you which workspace your client is bound to).
• Responses = { data } (single) · { data, meta } (cursor list) · BatchResultDto (issuance batch). Errors = RFC 9457 application/problem+json.

1. Issue a client (dashboard, once)

   In the admin-next sidebar, Developers › “New client”:

   • Copy client_id + client_secret once, on screen — this is the only time they’re shown. The platform keeps only a hash and cannot show them again. If lost, rotate.
   • Select scopes (deny-by-default · least privilege): clubs:read · billing:read · achievements:read · achievements:manage · designs:read · designs:manage · issuance:read · issuance:write · issuance:revoke · events:read.

2. Get a token (every 15 minutes · server-side)

   curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d 'grant_type=client_credentials' \
     -d 'scope=kolleges:openapi:issuance:write kolleges:openapi:issuance:read' \
     https://auth.kolleges.net/token
   # → { "access_token": "<ES256 JWT>", "token_type": "Bearer", "expires_in": 900, "scope": "…" }

   Always specify scope

   A token’s scope = requested scope ∩ the client’s registered scope. If you omit the scope parameter, the requested set is empty and a scopeless token is issued (the registered allow-list is not auto-delegated), and every /v2 call with that token returns 403. Include only the ops you need, explicitly.

3. Find your workspace (get clubDomain)

   Every other path is /v2/clubs/{clubDomain}/…, but the token does not carry the workspace domain. GET /v2/me gives it to you — the one route without clubDomain in the path, callable by any valid token with no particular scope.

   TOKEN=<access_token>
   
   curl -s -H "Authorization: Bearer $TOKEN" https://openapi.kolleges.net/v2/me
   # → { data: { clientId, clubDomain, operations } }
   
   CLUB=<clubDomain from the response>

   operations is what you can do right now

   operations is the intersection of the scopes carried by your token and the operations the workspace delegated to this client — the calls this token can actually make, so you can skip requests that would come back 403.

4. Call the API

   # Club identity and whether issuance is allowed
   curl -s -H "Authorization: Bearer $TOKEN" \
     https://openapi.kolleges.net/v2/clubs/$CLUB/
   # → { data: { domain, name, canIssue, grantedOperations } }

5. Issue (bulk · a single issuance = an array of one)

   curl -s -X POST -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -H "Idempotency-Key: order-2026-07-19-0001" \
     -d '{
           "achievementFormId": 123,
           "mode": "email",
           "recipients": [{ "externalUserId": "u-42", "name": "Jane Doe", "email": "jane@example.com" }]
         }' \
     https://openapi.kolleges.net/v2/clubs/$CLUB/issuances
   # → { results: [{ ref, status: "issued|skipped|failed", resourceId, error }],
   #     summary: { total, ok, skipped, failed } }

   Idempotency-Key is required

   Retrying with the same key returns the original result with no duplicate issuance. Retry safely on network failure.

6. Look up · files · revoke · events

   # List issuances (cursor)
   curl -s -H "Authorization: Bearer $TOKEN" "https://openapi.kolleges.net/v2/clubs/$CLUB/issuances?limit=20"
   # Detail (recipient PII)
   curl -s -H "Authorization: Bearer $TOKEN" "https://openapi.kolleges.net/v2/clubs/$CLUB/issuances/456"
   # Certificate file
   curl -s -H "Authorization: Bearer $TOKEN" "https://openapi.kolleges.net/v2/clubs/$CLUB/issuances/456/file?format=pdf" -o cert.pdf
   # Revoke (= invalidate)
   curl -s -X POST -H "Authorization: Bearer $TOKEN" "https://openapi.kolleges.net/v2/clubs/$CLUB/issuances/456/revoke"
   # Event feed
   curl -s -H "Authorization: Bearer $TOKEN" "https://openapi.kolleges.net/v2/clubs/$CLUB/events?limit=20"

Next steps

Learn more

• Authentication — token flow, scope, and key rotation in depth.
• Concepts — issuance, achievement, holder, and the response envelope.
• Errors — RFC 9457 problem+json.
• API reference — full endpoints, schemas, and interactive exploration.