An API for the systems you already run

Access & authentication

Machine clients use the OAuth 2.0 client-credentials grant. A client is issued a client ID and secret by a tenant administrator; the token endpoint returns a short-lived access token with the scopes granted to that client.

POST /api/v1/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "rr_client_...",
  "client_secret": "...",
  "scope": "attendance:read learners:read"
}

Send the token as Authorization: Bearer <token>. Human users authenticate through the web session with an httpOnly cookie and a CSRF-protected mutation policy. API keys are also supported for legacy integrations, with tier-based rate limits.

Quick start

1. Ask a tenant administrator to create an API client with the scopes you need.
2. Exchange the client credentials for an access token.
3. Call a scoped endpoint, for example the attendance register for a cohort.
4. Subscribe to a webhook if you need event-driven delivery.

curl -s https://rr-api.medq.co.zw/api/v1/tenant \
  -H "Authorization: Bearer $RR_TOKEN"

Every response is JSON with a success flag. Errors include a stable machine-readable error code and, where relevant, a requestId that matches the server log.

Scopes

Scope	Allows
attendance:read	Read attendance events and session certificates.
attendance:write	Submit offline attendance batches from verified edge hardware.
learners:read	Read learner demographics, identity state and consent status.
learners:write	Register learners and update compliance attributes.
stipends:read	Read SD5 calculations and locked pay runs.
payouts:initiate	Initiate a disbursement through a configured provider.
webhooks:manage	Create and revoke webhook subscriptions.
lms:sync	Synchronise roster and attendance with an LMS.
audit:read	Read audit entries and verify the chain.

A token can only do what its scopes and its tenant allow. Cross-tenant requests return 403 TENANT_SCOPE_VIOLATION.

Webhooks

Webhook requests carry an HMAC-SHA256 signature over the exact raw body. Verify the signature before parsing the JSON. Deliveries are retried with backoff and recorded in a delivery log.

X-RemoteRegister-Signature: sha256=<hex>
X-RemoteRegister-Event: attendance.batch.accepted
X-RemoteRegister-Delivery: dlv_...

Treat delivery as at-least-once. Use the delivery ID or the event's idempotency key to deduplicate.

Errors & rate limits

Status	Meaning
400	Malformed request or invalid state transition.
401	Missing, expired or invalid credentials.
403	Role, scope or tenant boundary violation.
404	Resource not found, including an unknown verification hash.
409	Duplicate resource or conflicting state.
422	Validation failure; the response lists the failing fields.
429	Rate limit exceeded; honour Retry-After and the X-RateLimit-* headers.

Rate limits are applied per client and per route class. The monitoring endpoint exposes current usage to tenant administrators. In multi-worker deployments, Redis-backed counters make the limit consistent across processes.

Mobile API

The mobile contract is served under /api/v1/mobile and is described in the same OpenAPI document, tagged Mobile Device API. It adds single-use pairing codes, Ed25519 request signatures, Play Integrity attestation, template-hash-only enrolment, bounded biometric matching and offline batch sync — because its security model differs from a server-to-server integration.

Every device request except /mobile/health carries a bearer access token plus X-RR-Device-Id, X-RR-Timestamp, X-RR-Nonce, X-RR-Content-SHA256 and X-RR-Device-Signature. The signature covers the method, canonical path and query, timestamp, nonce, body hash and device ID.

In live Play Integrity mode, the attestation token supplied to /mobile/activation/start must be at most ten minutes old and must carry a requestHash equal to the lowercase hex SHA-256 of the exact publicKeyPem string in the same request. A token therefore cannot be lifted from one activation and replayed against another key. Simulator mode labels its verdict and never presents it as a Google attestation.

GET /api/v1/mobile/health

POST /api/v1/mobile/activation/start
POST /api/v1/mobile/activation/complete
POST /api/v1/mobile/auth/refresh
GET  /api/v1/mobile/roster
POST /api/v1/mobile/enrolments
POST /api/v1/mobile/match
POST /api/v1/mobile/sync/batches

A no-match response never includes a candidate list, and 1:N searches are bounded to the device's assigned cohorts and venues. See Mobile & biometrics for the architecture and retention rules.

Environments

• Production: https://rr-api.medq.co.zw
• Staging: https://rr-staging.medq.co.zw
• Verification: https://rr-verify.medq.co.zw
• Status: https://rr-status.medq.co.zw

Staging may run integrations in simulator or sandbox mode. The status feed and the Trust Centre state which channels are live on a deployment.

Contract stability

Additive changes are announced in the changelog. Breaking changes are versioned in the path. The OpenAPI document at /api/v1/openapi.json is the source of truth for request and response shapes, including the public and mobile device tags.