DEVELOPER GUIDEREFERENCE CONTRACT

Mandate API

Represent delegation and mandate lifecycle independently from identity and ownership.

CONTRACT PRINCIPLES

The protocol carries business semantics.

Each integration must preserve authority, policy, evidence and recovery context.

Pin API/schema/profile versions in test evidence.

Carry a correlation ID across request, event, connector and evidence records.

Protect material write operations from accidental replay.

Never infer legal authority solely from transport success.

REFERENCE ENDPOINTS

The downloadable contract contains request/response models, OAuth scopes, idempotency and representative errors.

Reference API surface
Area	Reference route	Semantics
Resolver	GET /v1/resolve/{identifier}	Official ID → TTID resolution with authority context
DPP	GET /v1/dpp/{identifier}	Policy-qualified DPP read
Claims	POST /v1/claims	Evidence-backed claim submission
Evidence	POST /v1/evidence	Evidence/provenance reference
Mandate	POST /v1/mandates	Delegation lifecycle
Lifecycle	POST /v1/things/{thingId}/transitions	Material transition
Search	GET /v1/search	Derived read model
Connector	POST /v1/connectors/{id}/reconcile	Business reconciliation

POST/v1/mandates

Issue or submit a mandate/delegation record with explicit scope and expiry.

OAuth: mandate.write
State: Issuer is authenticated and authorized to delegate the requested scope. → Mandate enters governed lifecycle; it does not merge ownership and delegation semantics.
Evidence: Issuer, subject, scope, validity and supporting evidence.
Errors: 403 issuer lacks authority · 409 duplicate · 422 scope/expiry invalid
Retry: Use Idempotency-Key.

{"issuer":"owner:123","subject":"repairer:456","scope":["repair.write"],"validUntil":"2026-12-31T23:59:59Z"}

{"mandateId":"mandate:01...","status":"active-after-policy-evaluation"}

ARCHITECTURE WORKSHOP

Align product-group applicability, authority boundaries, portal journeys, integration contracts and evidence before committing to production claims.