Keys and sandbox
Live and sandbox keys, personal and organisation keys, scopes, expiry, IP allow-lists and keeping secrets safe.
Two kinds of key
| Live | Sandbox | |
|---|---|---|
| Prefix | edm_live_… | edm_sandbox_… |
| Runs AI | Yes | No: realistic canned results |
| Charges | API balance or paid credits | Never |
| LMS data | Your centre, as the key’s owner (or the organisation) | A fixed demo dataset |
| Jobs and files | Only live ones | Only sandbox ones |
| Webhooks | Yes | Yes, marked sandbox |
Scopes
A key can only do what its scopes allow. AI products use one scope per group, such as marking:write or learning:write. Reading a job needs jobs:read and the scope of the product that ran it (for example marking:write); report exports can only be read by keys of the person whose key made them. Uploading files needs files:write, which every write scope includes. LMS data uses <resource>:read and <resource>:write, for example learners:read.
A personal data key acts inside the key’s centre as the person who owns it (its sponsor). Each request needs the scope and that person’s current EduMark permission, so removing someone’s permission in EduMark also limits their keys. An organisation key needs only the scope, and acts with a centre administrator’s permissions in its own centre.
The full list of scopes is in the catalogue.
Personal and organisation keys
When you create a key, choose who owns it.
| Personal (“Just me”) | Organisation | |
|---|---|---|
| Belongs to | The person who made it | Your centre’s API project |
| When people leave | Stops working when its owner is removed, deleted or locked, or loses API access | Keeps working |
| Who can make one | Anyone who manages the centre’s API | Organisation administrators only |
| Rotate | Its owner, or an organisation administrator. It stays the owner’s key. | Organisation administrators only |
| Revoke | Anyone who manages the centre’s API | Organisation administrators only |
| LMS data | The owner’s current permissions | A centre administrator’s permissions, in this centre only |
Rotating never changes who owns a key. Keys made before you could choose are personal. Use an organisation key for a system that must keep running when staff change, such as a student records sync; changes it makes are recorded as made by the key itself.
Keeping keys safe
- Use keys only from your server. Never put a key in a browser, a mobile app or a public repository.
- Set an expiry (up to a year) and rotate keys before they expire. EduMark emails you seven days before. Rotating gives you a new secret with the same owner and stops the old one straight away, so put the new secret on your server as soon as you have it.
- Add an IP allow-list for production keys if your servers have fixed addresses.
- Revoke a key the moment you think it has leaked. Revocation takes effect immediately.