Authentication, API keys and scopes

View as Markdown

In short

Send a team API key as Authorization Bearer. Each key is named, stored only as a hash, limited to the scopes you tick, and can expire or be revoked at any time. The key decides the team; the address you call never does.

Sending the key

Send the key in the Authorization header as a Bearer token:

Authorization: Bearer ck_live_4kXbq0...

The X-API-Key header is accepted too, for clients that cannot set Authorization. If both are sent, Authorization: Bearer wins.

Keys are created by team administrators in Settings > Website & API > API keys (see the help guide Create and manage API keys). There is no API for creating keys.

How keys work

  • One team per key. Every request acts for the team that owns the key. The API never reads the team from the host name or from a user's session, so a key can only ever see its own team's data. Something that belongs to another team returns 404, not 403, so ids from other teams are never confirmed.
  • Shown once, stored as a hash. The full key (it starts with ck_live_) appears once, when it is created. Continuum stores only a SHA-256 hash and the first 12 characters, which the Website & API page shows so you can tell keys apart. A lost key cannot be recovered: revoke it and create another.
  • Named. Name keys after what uses them ("AMS sync", "Intranet"), and use one key per system, so you can revoke one without breaking the others.
  • Optional expiry. A key can be given an expiry date when it is created. It stops working at the end of that day.
  • Revocable. Revoking a key in Manage takes effect on the next request.
  • Last used. The Website & API page shows when each key was last used, updated at most once a minute.

Scopes

A key can only call the endpoints its scopes allow. A call outside them returns 403 with error.type permission_error and a message naming the missing scope. Give each key the fewest scopes it needs.

Scope What it allows
catalogue:read Read courses (public and private), their outline, course folders and events.
users:read Read users, the team's custom field definitions, groups and group members.
users:write Create, update, deactivate, reactivate and remove users.
groups:write Create, update and delete groups, and add or remove members.
enrolments:read Read enrolments, by user or by course.
enrolments:write Enrol users on courses and remove enrolments. Assigning a group to a course needs this and groups:write.
progress:read Read learner progress and results: percentage, dates, quiz scores, attendance, sign-off and certificate.
webhooks:manage Manage webhook endpoints and their deliveries. See Webhooks.
auth:sign_in_links Create one-time sign-in links for learners. See Sign-in links.
credentials:read Read issued course and programme certificates. See Credentials.
orders:read Read completed orders, invoices and credit notes. See Orders.

GET /me needs no scope. It returns the team and the key's own name, prefix, scopes, creation date and expiry, which is useful for a health check.

What a key can and cannot do

A key acts with roughly the authority of a team administrator, within its scopes. In particular:

  • Enrolling through the API takes no payment and skips approval, even on paid courses or courses that require approval. See Enrolments.
  • Users created through the API are always learners. The API never grants admin, author, billing or any other role.
  • Some accounts are protected: team administrators, owners, billing contacts, authors, outreach administrators, platform staff, people who also belong to another Continuum team, and (for some actions) linked presenters. For these, the API may change only team-local data such as custom fields and group membership. Changing their name or locale, writing their external id, deactivating or removing them returns 409 with error.code user_protected. See Users.

When the subscription lapses

Team state What the API does
Active or trialling Everything the key's scopes allow.
Payment overdue, in the restricted grace period Read-only: endpoints that need a :read scope work; anything else returns 403 permission_error saying the API is read-only until payment is made.
Subscription inactive Every request returns 403 permission_error.

Failed authentication

A missing, unknown, revoked or expired key returns 401 with error.type authentication_error. Repeated failures from one IP address are locked out for a short time: see Rate limits. A valid key is never locked out by someone else's failures.

Keeping keys safe

  • Keep keys on servers only: never in a browser, a mobile app or a public repository.
  • Store them in environment variables or a secrets manager, not in code.
  • Use one key per integration, with the fewest scopes it needs.
  • Set an expiry date on keys for short projects and contractors.
  • If a key may have leaked, revoke it straight away in Settings > Website & API, then create a replacement.

The legacy team key (v1)

Teams also have one older team API key, shown in the Team API key (v1, legacy) card. It authenticates API v1 (/api/v1/...) and the WordPress plugin's shared-key connections, and it does not work with v2. v1 is frozen: it keeps working but gets no new features. See Versioning and deprecation.

Frequently asked questions

Can one key work for several teams?

No. A key belongs to exactly one team. An organisation with several teams needs one key per team.

Can I see a key again after creating it?

No. Only a hash is stored. Revoke the key and create another one.

Can I change a key's scopes?

Not after it is created. Create a new key with the scopes you need, move your integration over, then revoke the old one.

Building an integration?

Tell us what you are connecting and we will help you plan it, or book a demo to see the API working.