Authentication

TL;DR: Send your organisation's API key as Authorization: Bearer <key> on every request. The key decides which organisation is calling, so no request names one.

Get a key

  1. MMW staff create your sandbox organisation and invite your admin.
  2. Your admin signs in and makes a key with POST /v1/api-keys, giving it a name such as the server that will hold it.
  3. The answer shows the whole key once. Only its hash is stored, so keep it in your secrets manager straight away.

Every key starts with mmwk_, so it is never mistaken for another credential. A sandbox organisation's keys start mmwk_test_ and reach synthetic data only; any other organisation's start mmwk_live_. Only your organisation's own admin can make, list or revoke its keys. The key list shows each key's kind and the minute it was last used.

To narrow a key, give it scopes when you make it: a list of the actions it may take, such as ["transcription.create", "primitive.read"]. A scoped key is refused anything else with 403 permission_denied. Leave scopes out and the key keeps every action a key may take. An empty list, or a scope a key may never hold, such as approval.create, is refused with 422 invalid_request, and no key is made.

Send it

curl -sS "$MMW_API_URL/v1/markings/<id>" \
  -H "Authorization: Bearer $MMW_API_KEY"

Keep the key on your server. Never put it in a browser, a mobile app or a repository.

What a key can reach

  • Your own organisation. The marking, transcription and feedback routes, your own files and jobs, and your organisation and its brand (GET /v1/organisations/{id}).
  • A school's data, only with that school's grant. A school grants your organisation access to named things, such as its classes. A request for a school that has not granted it gets 403 permission_denied.
  • Never another organisation's objects. An id that belongs to someone else is answered 404 not_found, the same as an id that does not exist.

What a key can never do

A key never corrects, approves or releases a mark, and never acknowledges a safeguarding flag. Each is 403 agent_not_allowed, whatever the key's organisation has been granted. A signed-in teacher or school admin does these in the app.

Revoke a key

POST /v1/api-keys/{id}/revoke ends a key. It is refused with 401 from the next request. Revoking a key that is already revoked changes nothing.

Rate limits

Each key, and your organisation as a whole, may make a set number of requests a minute. Every answer to a key carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the minute ends) for whichever limit is closer. A request over either limit is refused with 429 rate_limited and a Retry-After header in seconds, before it changes anything, so wait that long and send it again. A sandbox organisation's limits are lower than a live one's; ask MMW if you need more.

Creates and retries

Every create sends an Idempotency-Key header of your choosing, such as a UUID. Send the same request again with the same header and you get the first answer back, with nothing made twice. Keys are kept for 30 days.

Lists

Every list takes limit (1 to 100, default 50) and cursor, and answers { "data": [...], "nextCursor": "..." }. Pass nextCursor as cursor to read the next page. It is null on the last page.

Errors

Every refusal has the same body, { "error": { type, code, message, param, requestId, docUrl, retryable } }, and every answer carries a request-id header to quote to MMW, which the body repeats as requestId. The codes are listed in Error codes.