Authentication

Open API v2 uses the OAuth2 client_credentials grant. There are no long-lived static API keys — you exchange the credentials issued in the dashboard for a 15-minute ES256 access token and call with Authorization: Bearer. The design minimizes the exposure window.

The flow at a glance

1. Issue an API client from the Developers menu in the dashboard → client_id + client_secret.
2. Exchange for a 15-minute token at POST https://auth.kolleges.net/token (server-side · on every expiry).
3. Call https://openapi.kolleges.net/v2/… with the token as Authorization: Bearer.

Client authentication (client_secret)

Present client_id + client_secret via HTTP Basic.

curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d 'grant_type=client_credentials' \
  -d 'scope=kolleges:openapi:issuance:write' \
  https://auth.kolleges.net/token

Only a hash of the secret is stored

The client_secret is shown only once, on the issuance screen. The platform stores only a hash and cannot show it again. If lost, rotate it — rotation issues a new secret and invalidates the previous one.

Token properties

Property	Value
Algorithm	ES256 (JWT)
Lifetime	900 seconds (15 minutes)
audience (aud)	https://openapi.kolleges.net
issuer (iss)	https://auth.kolleges.net
scope	requested scope ∩ the client’s registered scope

audience isolation

The aud of an Open API v2 token is fully isolated from other Kolleges API surfaces. You can’t call another surface with an openapi token, and vice versa — credentials don’t cross lanes.

Scope (least privilege)

Scopes live in the kolleges:openapi:<operation> namespace. deny-by-default — you can only request scopes registered on the client, and a token carries only the intersection of requested ∩ registered.

Don't omit 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). Every /v2 call with that token returns 403. Request only the operations you need, explicitly.

scope	Purpose
kolleges:openapi:clubs:read	Club identity · whether issuance is allowed
kolleges:openapi:issuance:read	Issuance list · detail · file
kolleges:openapi:issuance:write	Issue
kolleges:openapi:issuance:revoke	Revoke (invalidate)
kolleges:openapi:achievements:read / :manage	Read / author achievements
kolleges:openapi:designs:read / :manage	Read / author designs
kolleges:openapi:billing:read	Billing · entitlements
kolleges:openapi:events:read	Event feed

Key rotation

If a client_secret leaks or needs periodic replacement, rotate it from the dashboard. Right after rotation the new and old secrets are both briefly valid (zero-downtime rollover), so token issuance isn’t interrupted mid-deploy. Once the rollover is complete, the previous secret is invalidated.