Candidate contractREST JSONVersion 0.3

API guide

A public view of the planned lifecycle and resources. This page prepares integrations; it is not yet a stable API contract.

Conventions Events Reports

HTTP baseline

Candidate conventions

HTTPS exchanges with UTF-8 JSON bodies.
Access token limited to an organisation, roles and scopes.
Opaque identifiers; tenant_id is derived from authorisation and never trusted as access proof.
Idempotency-Key header required for replayable mutations.
RFC 3339 UTC timestamps and a correlation identifier in every response.
Cursor pagination for collections; no raw biometric data in the API.

Access is not open yet.

The base URL, token issuance, final scopes and quotas are not published. Integration secrets will never be delivered through this website.

Nominal lifecycle

Create and conclude a verification

Create an event with its context, time window and requested level.
Add authorised participants and activate the event.
Start a round; applications perform the required controls.
Read a factual verdict and any degradation reasons.
Complete the event, then request a report and evidence bundle.

Illustrative exampleHTTP

POST /events
Authorization: Bearer <access_token>
Idempotency-Key: 7dd95eb4-5983-48c6-80bd-a7a857ba0e9a
Content-Type: application/json

{
  "context": "Executive committee, 8 April 2026",
  "assurance_level": "HIGH",
  "starts_at": "2026-04-08T08:00:00Z",
  "ends_at": "2026-04-08T10:00:00Z"
}

Field names and values may change before a stable OpenAPI specification is released.

Business resources

Events and participants

POST/events

Create a time-bounded event.

GET/events/{event_id}

Read context and current state.

PATCH/events/{event_id}

Edit a draft before activation.

POST/events/{event_id}/activate

Freeze the applicable policy and open the event.

POST/events/{event_id}/participants

Invite a participant under minimisation rules.

GET/events/{event_id}/participants

Read authorised factual statuses.

POST/events/{event_id}/complete

Close the event and prevent new rounds.

Interactive presence

Rounds and challenges

POST/events/{event_id}/rounds

Start a control with a fresh temporal context.

POST/rounds/{round_id}/subjects/{subject_id}/ready

Confirm readiness from the subject’s bound device.

GET/challenges/{challenge_id}

Retrieve the challenge authorised for the caller.

POST/challenges/{challenge_id}/observations/finalize

Finalise a signed observation.

POST/rounds/{round_id}/finalize

Stop collection and calculate the result.

GET/rounds/{round_id}/verdict

Read the achieved level and associated reasons.

Raw frames, challenge secrets and anti-fraud parameters are not exposed through management APIs.

Evidence

Reports and verification

POST/events/{event_id}/reports

Create a report from a completed event.

GET/reports/{report_id}

Read metadata and generation status.

GET/reports/{report_id}/bundle

Download the authorised evidence bundle.

POST/reports/verify

Verify the integrity and signatures of a bundle.

Evidence is not a business decision.

The API reports completed controls and their limits. Integrators remain responsible for payment, authorisation and approval rules.

Predictable contracts

Statuses and errors

HTTP	Use	Expected behaviour
`400`	Invalid request	Correct the reported fields.
`401`	Missing or expired authentication	Obtain a fresh token.
`403`	Insufficient scope, role or tenant	Do not retry without an authorisation change.
`409`	Incompatible state or idempotency conflict	Read the resource before acting again.
`422`	Business rule not satisfied	Display the reason; never turn failure into success.
`429`	Temporary limit	Honor `Retry-After` with backoff.

Illustrative shapeJSON

{
  "error": {
    "code": "EVENT_NOT_ACTIVE",
    "message": "The event is not active.",
    "correlation_id": "req_01J...",
    "retryable": false
  }
}