Skip to main content
Free academy website with paid plans.

Get started

Authentication and scopes

How the /v1 API checks a Bearer credential, the two key types, and the scope each route needs.

Updated

Browse the developer docs

Steps

  1. Send every request with Authorization: Bearer <token>. The word Bearer is not case sensitive. A missing or malformed header returns 401 unauthorized.
  2. Use an API key (prefix ck_live_) for an integration that acts for the academy. Use a personal access token (prefix ck_pat_) when the call should act as one person. You create both in the Create API key dialog by choosing API key or Personal access token under Kind.
  3. A key is its prefix followed by 48 lowercase hex characters. A token that starts with ck_ but does not have exactly this shape is rejected with 401 before any lookup.
  4. Grant only the scopes the integration needs. The scopes are students:read, students:write, events:read, webhooks:read, webhooks:write, mcp:read, mcp:write and mcp:admin.
  5. Match scopes to routes: GET /v1/students needs students:read. POST /v1/students and POST /v1/students/{id}/notes need students:write. GET /v1/events needs events:read. GET /v1/webhook_endpoints/{id}/deliveries needs webhooks:read. POST /v1/webhook_endpoints, DELETE /v1/webhook_endpoints/{id} and POST /v1/webhook_deliveries/{id}/replay need webhooks:write.
  6. If the credential lacks the scope a route needs, the API returns 403 forbidden with the message "this credential is missing the required scope: <scope>".

Notes

  • The mcp:read, mcp:write and mcp:admin scopes can only be given to a personal access token. Trying to add them to an API key fails.
  • The academy is taken from the key itself, never from the URL, headers or body. A key can only reach its own academy’s data.
  • Unknown, revoked and expired keys all return the same 401 "invalid credential".
  • Creating and revoking keys needs the integration write permission. Viewing the key list needs integration read. Owner and admin roles have both by default.
  • The API also accepts OAuth2 access tokens issued to an installed OAuth app. Their scopes are the token’s scopes that the installation still grants. A revoked installation stops its tokens at once.

Related guides

Still need help?

Email hello@chesscore.io. Using ChessCore day to day? Visit the Help centre.