POST /programs
Accepts an Institution Profile plus programUri and databoxBaseUrl (HTTPS; HTTP only for loopback). Returns a summary with profile id/version, record and submission classes — no customer data.
Control plane
Mapping Smithy HTTP API.
A thin JSON control plane, intentionally separate from the public Databox data plane. In the live preset it is mounted at /.databox/smithy.
Base URL & authentication
Control-token boundary.
| Item | Value |
|---|---|
| Base | http://localhost:3000/.databox/smithy |
| Auth | Authorization: Bearer <control-token> — token must be ≥ 32 bytes; comparison is constant-time |
| Missing/invalid | 401 with WWW-Authenticate: Bearer realm="databox-control" |
| Body limit | 1 MB; bodies must be valid JSON |
| Caching | Cache-Control: no-store |
Endpoints
Programs, mappings, source-events.
| Method | Path | Success | Purpose |
|---|---|---|---|
GET | /programs | 200 | List registered program summaries |
POST | /programs | 201 | Register and validate an Institution Profile |
POST | /mappings | 201 | Provision an opaque relationship and issue a connection credential |
POST | /source-events | 202 | Transform and commit an institutional event; issue a receipt |
POST /mappings
Takes control-plane PII (customerId, namespace, pairwise WebID, holder JWK). Returns opaque provisioning plus a signed connection credential. Raw customerId is absent from the result.
POST /source-events
Deposits a source-system event as a record. recordClass, legalBasis and purpose must be declared in the profile. Replayed sourceEventId values are rejected.
Local live preset
Start the demonstration server.
npm install npm run build $token = [Convert]::ToHexString( [Security.Cryptography.RandomNumberGenerator]::GetBytes(32)) npm.cmd run start:databox-live -- ` --databoxControlToken $token ` --baseUrl http://localhost:3000/ ` --port 3000
Invariants enforced here
PII stays in the control plane. The raw customer ID never enters a response body, resource URL or receipt. Fail-closed validation applies to profiles, classes, bases and purposes. Any other route returns 404 {"error":"not-found"}.
Related