# OpenDPP Integration API — full knowledge bundle (OKF v0.2) > This file concatenates the entire OpenDPP knowledge bundle for one-shot ingestion by AI agents. The > canonical, individually-addressable concepts live under https://opendpp-node.eu/okf/ and at > https://opendpp-node.eu/openapi.json. API version: 1.14.0. ================================================================================ # FILE: /okf/overview.md ================================================================================ --- type: Reference title: OpenDPP Integration API — overview description: What the OpenDPP Integration API does, how it is organised, and where to start. resource: https://opendpp-node.eu/api-reference tags: - overview - getting started - ESPR - EU Battery Regulation generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- OpenDPP is a B2B platform for **EU Digital Product Passports (DPPs)**, aligned with the data requirements of the ESPR and the EU Battery Regulation. This knowledge bundle is a machine-readable projection of the **public integration surface**: everything an external system needs to create, validate, seal, publish, resolve and verify passports. It is generated from the same OpenAPI 3.1 document served at [`/openapi.json`](https://opendpp-node.eu/openapi.json); the human-readable reference is at [`/api-reference`](https://opendpp-node.eu/api-reference). # What you can do - **Create & validate** SKU/type-level passports against ESPR category rules — see [createPassport](/operations/createPassport.md) and the dry-run [validatePassport](/operations/validatePassport.md). - **Seal** a passport with an **advanced** electronic seal and **verify** it offline — see [sealPassport](/operations/sealPassport.md) and [verifyPassportSeal](/operations/verifyPassportSeal.md), and the [sealing & verification](/guides/sealing-and-verification.md) playbook. - **Serialise** individual battery units (GS1 AI 21) and append telemetry — the [Battery Units](/tags/battery-units.md) tag. - **Resolve** a passport publicly with content negotiation (JSON-LD / AAS / UNTP credential / HTML) — the [Public Resolution](/tags/public-resolution.md) tag. - **Subscribe** to lifecycle events over signed webhooks — the [Webhooks](/tags/webhooks.md) tag. # How this bundle is organised | Directory | Contents | |-----------|----------| | [`guides/`](/guides/index.md) | Curated integration playbooks and references (auth, errors, rate limits, access tiers, sealing, interop, conformance). | | [`tags/`](/tags/index.md) | One overview per API domain, each linking to its operations. | | [`operations/`](/operations/index.md) | One concept per endpoint (method, path, parameters, request/response shapes, a curl example). | | [`schemas/`](/schemas/index.md) | One concept per request/response object, with its JSON Schema and the operations that use it. | | [`webhooks/`](/webhooks/index.md) | The lifecycle events you can subscribe to. | # Four URL zones The API spans four kinds of path: the versioned `/api/v1/*` management surface (the bulk), unversioned **public resolution** roots (`/passport`, `/01`, `/8003`, `/unit`, `/context/v1`), a `/.well-known/` certificate path, and the ops endpoints (`/health`, `/api/v1/version`). Start with [authentication](/guides/authentication.md). ================================================================================ # FILE: /okf/guides/index.md ================================================================================ # Guides * [Authentication & tenancy](authentication.md) - Authenticate with a tenant API key as a Bearer token; tenant identity is token-bound. * [Error model](errors.md) - Error envelopes returned by the API, including the richer ESPR validation-failure shape. * [Rate limits](rate-limits.md) - The per-key plan ladder, the per-IP ceiling, and which of the two bites first. * [Public access tiers](public-access-tiers.md) - How one resolution URL serves tiered views via capability tokens. * [Sealing & verification](sealing-and-verification.md) - Apply an advanced electronic seal and verify it offline from the redacted document. * [Interop: AAS & UNTP credentials](interop-aas-untp.md) - The standards-conformant projections OpenDPP serves alongside JSON-LD, and where to validate them. * [Conformance honesty](conformance.md) - What OpenDPP's output conforms to today, what is partial, and what is on the roadmap. ================================================================================ # FILE: /okf/guides/authentication.md ================================================================================ --- type: Playbook title: Authentication & tenancy description: Authenticate with a tenant API key as a Bearer token; tenant identity is token-bound. resource: https://opendpp-node.eu/api-reference tags: - authentication - api keys - tenancy - security generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Authenticate with a tenant **API key** sent as a Bearer token: ``` Authorization: Bearer op_dpp_token_… ``` Keys are created in the Client Console (Developers → API keys), are shown **once** at creation, carry a role plus optional narrowed permissions and optional expiry, and can be revoked at any time. API-key clients are exempt from CSRF requirements. Public endpoints (the [Public Resolution](/tags/public-resolution.md) tag, the public validators, and the audit verifier) need no credentials — see [public access tiers](/guides/public-access-tiers.md). # Tenancy Tenant identity is **token-bound** — it is derived from your API key, never from the request host. The same paths work on the apex host (`https://opendpp-node.eu`) and on tenant workspace hosts (`https://.opendpp-node.eu`); when a workspace host is used it must match the key's tenant, or the request is rejected with `403`. # Check your identity Call [whoami](/operations/whoami.md) to see the workspace, role, permissions, operator scope, and passport usage against your tier quota for the presented key. # Write-operation gates Write operations are subject to subscription gating (**402** when a workspace subscription has lapsed) and, where the workspace enforces it, MFA (**403**). Cookie-authenticated browser sessions must additionally send the `X-CSRF-Token` double-submit header; Bearer API-key clients do not. ================================================================================ # FILE: /okf/guides/errors.md ================================================================================ --- type: Reference title: Error model description: Error envelopes returned by the API, including the richer ESPR validation-failure shape. resource: https://opendpp-node.eu/api-reference tags: - errors - validation - troubleshooting generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Authenticated endpoints return `{ success: false, error, message }` (some endpoints, and all public-resolution errors, omit `success` and return only `error` + `message`). # Validation failures ESPR metadata validation failures return a richer shape with per-field `errors[]` (plus `warnings[]` when any exist — the key is omitted entirely when there are none). `friendlyMessage` texts are localizable via `?lang=` or `Accept-Language` (28 languages, default `en`). See [ValidationErrorItem](/schemas/ValidationErrorItem.md) and the dry-run validators [validatePassport](/operations/validatePassport.md) / [validatePassportPublic](/operations/validatePassportPublic.md). Bulk endpoints report row-level problems as `errors: string[]`. Malformed JSON and query-string violations return a default `{ statusCode, code, error, message }` body. # Status codes you will encounter | Status | Meaning | |--------|---------| | `400` | Bad request or ESPR validation failed. | | `401` | Missing/invalid/revoked/expired credentials. | | `402` | Workspace subscription lapsed — writes blocked, reads unaffected. | | `403` | Authenticated but not allowed (permission, cross-workspace, or MFA-gated write). | | `404` | Resource not found or not visible to your workspace. | | `409` | Duplicate (e.g. a `(productId, operatorId)` pair that already exists). | | `413` | Request body over the per-endpoint limit. | | `429` | Rate limit exceeded — see [rate limits](/guides/rate-limits.md). | | `5xx` | Unexpected server error; details are logged server-side and never returned. | ================================================================================ # FILE: /okf/guides/rate-limits.md ================================================================================ --- type: Reference title: Rate limits description: The per-key plan ladder, the per-IP ceiling, and which of the two bites first. resource: https://opendpp-node.eu/api-reference tags: - rate limits - throttling - headers - tiers generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Two limits apply, and which one binds depends on how you call. ## Per API key (authenticated calls) | Plan | Per-key budget | |------|----------------| | Growth | **120 requests/min** | | Scale | **600 requests/min** | | Enterprise | **unlimited** | A second ceiling of **3x that rate** applies across all of a workspace's keys together, so issuing more keys divides throughput fairly between your own systems rather than multiplying it. Plans below Growth do not include API access. Exceeding either budget returns `429` with a `Retry-After` header. ## Per IP (all traffic) | Surface | Limit | Headers | |---------|-------|---------| | Anonymous, all endpoints | **100 requests/min per IP** (authenticated calls sit on a higher ceiling) | `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-reset` | | Public passport resolution | **30 requests/min per IP** | none | | Public validator | **10 requests/min per IP** | none | | GS1 decode / check-digit helpers, anonymous | **2 requests/min per IP** | `x-ratelimit-*` | Every plan that can reach the API sits at or above the anonymous figure, so an authenticated caller never meets a stricter limit than the per-IP number. Stay under these limits with client-side queueing. On `429`, back off until `Retry-After` (or the `x-ratelimit-*` window, where present) has elapsed. With `Accept: text/html`, the public resolver returns an HTML page on `429` instead of JSON. A `429` never indicates a credential problem — an invalid or revoked key returns `401`, so do not rotate a key in response to rate limiting. ================================================================================ # FILE: /okf/guides/public-access-tiers.md ================================================================================ --- type: Reference title: Public access tiers description: How one resolution URL serves tiered views via capability tokens. resource: https://opendpp-node.eu/api-reference tags: - access - tiers - capability tokens - legitimate interest generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Public resolution endpoints serve **tiered** views of the same URL: - **Public tier** — anonymous callers see the public, redacted view. - **Legitimate-interest tier** — holders of a `dpp_li_…` capability token see the restricted fields unlocked under the EU Battery Regulation (e.g. for batteries, Annex XIII parts 2–4: `detailedPerformance`, `lifecycleAndInUse`, `circularityAndDisassembly`). - **Authority tier** — holders of a `dpp_auth_…` token see the authority view. - **Owner tier** — the issuing tenant's own credentials see everything. Capability tokens are presented as a Bearer token or a `?grant=` query parameter. Third parties request access via the hosted request page; issuers manage grants through the [Access Grants](/tags/access-grants.md) tag ([createGrant](/operations/createGrant.md), [approveGrantRequest](/operations/approveGrantRequest.md), [revokeGrant](/operations/revokeGrant.md)). Privileged fields such as facility street addresses are never published at the public tier. ================================================================================ # FILE: /okf/guides/sealing-and-verification.md ================================================================================ --- type: Playbook title: Sealing & verification description: Apply an advanced electronic seal and verify it offline from the redacted document. resource: https://opendpp-node.eu/security tags: - sealing - verification - eIDAS - merkle - RFC 3161 generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- OpenDPP passport seals are **advanced electronic seals**: an ECDSA P-256 signature over a Merkle root of the passport content, with an optional RFC 3161 timestamp. (This is an *advanced* seal — a *qualified* seal would require a QTSP; OpenDPP does not issue qualified seals.) # Seal a passport Call [sealPassport](/operations/sealPassport.md) with `passport:seal`. The tenant signing key is generated and held server-side in an encrypted vault and is never returned; rotate it with [rotateTenantKeys](/operations/rotateTenantKeys.md). # Verify a seal Anyone can verify a seal — no account required. [verifyPassportSeal](/operations/verifyPassportSeal.md) recomputes every Merkle leaf from the submitted values, so it requires the **unredacted** document (caller-supplied redacted-leaf hashes are deliberately not trusted) and checks that the signing workspace is bound to the economic operator declared in the payload. # Offline verification of redacted documents Redacted documents stay verifiable **offline**: masked fields keep their true leaf hashes in `proof.redactedLeaves` (see [MerkleTreeAttestationProof](/schemas/MerkleTreeAttestationProof.md)), letting any verifier rebuild the sealed root without the privileged values. Download the platform seal-CA certificate from [getSealCaCertificate](/operations/getSealCaCertificate.md). > The legacy passport seal is a vendor **MerkleTreeAttestationProof**. The standards-conformant > credential is a *separate* artifact — see [interop: AAS & UNTP](/guides/interop-aas-untp.md). ================================================================================ # FILE: /okf/guides/interop-aas-untp.md ================================================================================ --- type: Reference title: "Interop: AAS & UNTP credentials" description: The standards-conformant projections OpenDPP serves alongside JSON-LD, and where to validate them. resource: https://github.com/OpenDPP/opendpp-interop tags: - interop - AAS - IDTA - UNTP - data integrity generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Public resolution is **content-negotiated**: one URL serves several representations, so a passport never drifts between formats. Set the `Accept` header on [resolvePublicPassport](/operations/resolvePublicPassport.md), the GS1 resolvers, or [getPassport](/operations/getPassport.md): | `Accept` | Representation | |----------|----------------| | (default) | W3C JSON-LD passport document | | `application/aas+json` | Asset Administration Shell (AAS) v3.0 Environment, validated against the official IDTA-01001-3-1 schema | | `application/vc+jwt` | A conformant UNTP DigitalProductPassport credential, signed as an enveloping JOSE `vc+jwt` (ES256) | | `application/vc+ld+json` | The same credential with an embedded W3C **Data Integrity** proof (cryptosuite `ecdsa-jcs-2019`, RFC 8785 JCS, multibase base58btc) | | `text/html` | The human passport page | The per-unit resolver [resolvePublicBatteryUnit](/operations/resolvePublicBatteryUnit.md) also serves the item-granularity `vc+jwt` and `vc+ld+json` counterparts. # Validate it yourself The interoperability boundary — the official AAS + UNTP schemas, live-reproducible samples, an offline conformance validator, and the AAS + UNTP field mappings — is **open source** at [github.com/OpenDPP/opendpp-interop](https://github.com/OpenDPP/opendpp-interop) (Apache-2.0). It lets any integrator validate and verify OpenDPP's standards-conformant output without access to the product source. See also the [conformance](/guides/conformance.md) honesty matrix. ================================================================================ # FILE: /okf/guides/conformance.md ================================================================================ --- type: Reference title: Conformance honesty description: What OpenDPP's output conforms to today, what is partial, and what is on the roadmap. resource: https://github.com/OpenDPP/opendpp-interop tags: - conformance - standards - honesty generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- OpenDPP is deliberately precise about what it claims. In short: - **ESPR / EU Battery Regulation** — the platform is built for **readiness** against the ESPR data requirements and the EU Battery Regulation. Whether a given product is *compliant* is the operator's determination, not OpenDPP's. - **AAS (IDTA)** — the AAS v3.0/3.1 Environment is CI-validated against the official IDTA AAS metamodel 3.1 schema (IDTA-01001-3-1). Concepts OpenDPP coins itself are honestly namespaced `urn:opendpp:*`, never presented as eCl@ss. - **UNTP / W3C Data Integrity** — the per-passport credential is a conformant UNTP DigitalProductPassport credential, emitted both as an enveloping `vc+jwt` and as an embedded `ecdsa-jcs-2019` Data Integrity proof, and CI-validated against the official UNTP DPP schema and the off-the-shelf `@digitalbazaar` cryptosuite. - **The legacy passport seal** is a vendor `MerkleTreeAttestationProof` — an *advanced* (not qualified) electronic seal. It is never presented as the conformant credential; that is a separate artifact. The authoritative per-path conform / partial / roadmap matrix lives in the open-source interop kit at [github.com/OpenDPP/opendpp-interop](https://github.com/OpenDPP/opendpp-interop). No competent authority certifies, verifies, or approves a product or passport through OpenDPP. ================================================================================ # FILE: /okf/tags/index.md ================================================================================ # API domains * [Passports](passports.md) - Create, validate, read, update, seal and manage the lifecycle of Digital Product Passports. * [Economic Operators](economic-operators.md) - Register and manage the economic operators (manufacturers/brands, identified by EORI or national registry id) that passports are issued on behalf of. * [Battery Units](battery-units.md) - Per-unit battery serialization (real serials, GS1 AI 21) under a SKU-level passport, plus append-only telemetry events (state of health, charge cycles, status… * [Facilities](facilities.md) - Manufacturing facility master data, identified by GS1 GLN-13 (the Unique Facility Identifier). * [Access Grants](access-grants.md) - Capability tokens implementing tiered legitimate-interest access: issue, approve, deny and revoke dpp_li_… / dpp_auth_… tokens. * [Webhooks](webhooks.md) - Subscribe HTTPS endpoints to passport lifecycle events. * [Traceability & Audit](traceability-audit.md) - UNTP/EPCIS supply-chain traceability events, lineage queries, and the public seal verifier. * [Public Resolution](public-resolution.md) - Unauthenticated, content-negotiated passport resolution: GS1 Digital Link paths, passport and unit pages. * [Verifiable Credentials](verifiable-credentials.md) - Issuer trust endpoints that back the UNTP Verifiable Credential representations: the workspace's did:web DID document (public keys only) and its W3C Bitstring… * [Schemas & Vocabulary](schemas-vocabulary.md) - Machine-readable contracts: per-category ESPR JSON Schemas, the W3C JSON-LD context, and the curated materials vocabulary. * [QR Codes](qr-codes.md) - Export GS1-Digital-Link QR codes (PNG/SVG, 128–2048 px, GS1 quiet zone) for passports and battery units. * [eIDAS Keys](eidas-keys.md) - Tenant signing-key management. * [Account](account.md) - Identity of the authenticated API key / session: workspace, role, permissions, operator scope, and passport usage against the tier quota — the integration-faci… * [Service](service.md) - Service metadata and liveness. ================================================================================ # FILE: /okf/tags/passports.md ================================================================================ --- type: Reference title: Passports description: Create, validate, read, update, seal and manage the lifecycle of Digital Product Passports. resource: https://opendpp-node.eu/api-reference tags: - api domain - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Create, validate, read, update, seal and manage the lifecycle of Digital Product Passports. Passport metadata is category-specific: machine-readable JSON Schemas are served live at `GET /api/v1/schemas/{category}` for textiles, batteries, electronics, chemicals and construction; the remaining categories (cosmetics, toys, iron-steel, aluminium) are validated by built-in rules — use the dry-run validators to check payloads for any category. ## Operations - [listPassports](/operations/listPassports.md) — `GET /api/v1/passports` — List passports in your workspace (paginated JSON-LD) - [createPassport](/operations/createPassport.md) — `POST /api/v1/passports` — Create (ingest) a Digital Product Passport - [validatePassport](/operations/validatePassport.md) — `POST /api/v1/passports/validate-only` — Dry-run ESPR validation of passport metadata (nothing is stored) - [validatePassportPublic](/operations/validatePassportPublic.md) — `POST /api/v1/passports/validate-only-public` — Permission-free dry-run ESPR metadata validation (strictly rate-limited) - [bulkIngestPassports](/operations/bulkIngestPassports.md) — `POST /api/v1/passports/bulk` — Bulk-ingest up to 200 passports with per-row error reporting - [ingestPassportFromAas](/operations/ingestPassportFromAas.md) — `POST /api/v1/passports/aas/ingest` — Ingest a passport from an AAS JSON Environment (seal-verified) - [passportVcReadinessReport](/operations/passportVcReadinessReport.md) — `GET /api/v1/passports/vc-readiness` — Catalog-wide UNTP Verifiable-Credential readiness report - [getPassport](/operations/getPassport.md) — `GET /api/v1/passports/{id}` — Fetch a single passport (content-negotiated JSON-LD / AAS / HTML) - [updatePassport](/operations/updatePassport.md) — `PUT /api/v1/passports/{id}` — Update passport metadata (versioned to history) - [deleteDraftPassport](/operations/deleteDraftPassport.md) — `DELETE /api/v1/passports/{id}` — Permanently delete a DRAFT passport - [sealPassport](/operations/sealPassport.md) — `POST /api/v1/passports/{id}/seal` — Apply the tenant's advanced electronic seal - [updatePassportStatus](/operations/updatePassportStatus.md) — `PUT /api/v1/passports/{id}/status` — Transition passport lifecycle status (recall / decommission / reactivate) ================================================================================ # FILE: /okf/tags/economic-operators.md ================================================================================ --- type: Reference title: Economic Operators description: Register and manage the economic operators (manufacturers/brands, identified by EORI or national registry id) that passports are issued on behalf of. resource: https://opendpp-node.eu/api-reference tags: - api domain - economic-operators generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Register and manage the economic operators (manufacturers/brands, identified by EORI or national registry id) that passports are issued on behalf of. Operators with passports are archived — never hard-deleted — so their passports stay resolvable. ## Operations - [listOperators](/operations/listOperators.md) — `GET /api/v1/operators` — List economic operators bound to your workspace - [registerOperator](/operations/registerOperator.md) — `POST /api/v1/operators` — Register an economic operator and bind it to your workspace - [getOperator](/operations/getOperator.md) — `GET /api/v1/operators/{id}` — Fetch a single bound economic operator - [updateOperator](/operations/updateOperator.md) — `PATCH /api/v1/operators/{id}` — Update an operator's name or role (regId is immutable) - [deleteOperator](/operations/deleteOperator.md) — `DELETE /api/v1/operators/{id}` — Remove an operator (archives if it has passports, else hard-deletes) - [restoreOperator](/operations/restoreOperator.md) — `POST /api/v1/operators/{id}/restore` — Restore an archived operator and its archived passports ================================================================================ # FILE: /okf/tags/battery-units.md ================================================================================ --- type: Reference title: Battery Units description: Per-unit battery serialization (real serials, GS1 AI 21) under a SKU-level passport, plus append-only telemetry events (state of health, charge cycles, status changes) per the EU Battery Regulation. resource: https://opendpp-node.eu/api-reference tags: - api domain - battery-units generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Per-unit battery serialization (real serials, GS1 AI 21) under a SKU-level passport, plus append-only telemetry events (state of health, charge cycles, status changes) per the EU Battery Regulation. ## Operations - [validateBatteryUnits](/operations/validateBatteryUnits.md) — `POST /api/v1/passports/{passportId}/units/validate` — Pre-flight: validate battery-unit identifiers without persisting - [listBatteryUnits](/operations/listBatteryUnits.md) — `GET /api/v1/passports/{passportId}/units` — List serialised battery units under a passport - [serializeBatteryUnits](/operations/serializeBatteryUnits.md) — `POST /api/v1/passports/{passportId}/units` — Serialise individual battery units under a passport (bulk, up to 200) - [getBatteryUnit](/operations/getBatteryUnit.md) — `GET /api/v1/units/{id}` — Get one battery unit as JSON-LD with its dynamic-data history - [deleteBatteryUnit](/operations/deleteBatteryUnit.md) — `DELETE /api/v1/units/{id}` — Not deletable: a serialised unit is a marketed physical item (always 409) - [listBatteryUnitEvents](/operations/listBatteryUnitEvents.md) — `GET /api/v1/units/{id}/events` — List a battery unit's telemetry history (newest first, cursor-paginated) - [recordBatteryUnitEvent](/operations/recordBatteryUnitEvent.md) — `POST /api/v1/units/{id}/events` — Append an immutable telemetry event to a battery unit - [bulkRecordBatteryUnitEvents](/operations/bulkRecordBatteryUnitEvents.md) — `POST /api/v1/units/{id}/events/bulk` — Append a batch of telemetry events to a battery unit ================================================================================ # FILE: /okf/tags/facilities.md ================================================================================ --- type: Reference title: Facilities description: Manufacturing facility master data, identified by GS1 GLN-13 (the Unique Facility Identifier). resource: https://opendpp-node.eu/api-reference tags: - api domain - facilities generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Manufacturing facility master data, identified by GS1 GLN-13 (the Unique Facility Identifier). GLN, name, activity and country are public in passport documents; street addresses are never published. ## Operations - [listFacilities](/operations/listFacilities.md) — `GET /api/v1/facilities` — List facilities in the tenant workspace - [createFacility](/operations/createFacility.md) — `POST /api/v1/facilities` — Register a facility (GS1 GLN) - [getFacility](/operations/getFacility.md) — `GET /api/v1/facilities/{id}` — Get a single facility - [updateFacility](/operations/updateFacility.md) — `PUT /api/v1/facilities/{id}` — Update facility master data (GLN is immutable) - [deleteFacility](/operations/deleteFacility.md) — `DELETE /api/v1/facilities/{id}` — Delete a facility (passports are unlinked, never deleted) ================================================================================ # FILE: /okf/tags/access-grants.md ================================================================================ --- type: Reference title: Access Grants description: "Capability tokens implementing tiered legitimate-interest access: issue, approve, deny and revoke dpp_li_… / dpp_auth_… tokens." resource: https://opendpp-node.eu/api-reference tags: - api domain - access-grants generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Capability tokens implementing tiered legitimate-interest access: issue, approve, deny and revoke `dpp_li_…` / `dpp_auth_…` tokens. Third parties request access via the hosted request page; granted tokens unlock restricted fields on the public resolution endpoints (Bearer or `?grant=`). ## Operations - [listGrants](/operations/listGrants.md) — `GET /api/v1/grants` — List access grants and pending access requests - [createGrant](/operations/createGrant.md) — `POST /api/v1/grants` — Issue a legitimate-interest access grant directly - [approveGrantRequest](/operations/approveGrantRequest.md) — `POST /api/v1/grants/{id}/approve` — Approve a pending access request and mint its token - [denyGrantRequest](/operations/denyGrantRequest.md) — `POST /api/v1/grants/{id}/deny` — Deny a pending access request - [revokeGrant](/operations/revokeGrant.md) — `DELETE /api/v1/grants/{id}` — Revoke an access grant (soft revocation) ================================================================================ # FILE: /okf/tags/webhooks.md ================================================================================ --- type: Reference title: Webhooks description: Subscribe HTTPS endpoints to passport lifecycle events. resource: https://opendpp-node.eu/api-reference tags: - api domain - webhooks generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Subscribe HTTPS endpoints to passport lifecycle events. Deliveries are HMAC-SHA256-signed POSTs with retry/backoff — see the webhooks section of this document for the signature scheme and payloads. ## Operations - [listWebhookSubscriptions](/operations/listWebhookSubscriptions.md) — `GET /api/v1/webhooks/subscriptions` — List webhook subscriptions (signing secrets stripped) - [createWebhookSubscription](/operations/createWebhookSubscription.md) — `POST /api/v1/webhooks/subscriptions` — Register a webhook subscription (signing secret returned once) - [updateWebhookSubscription](/operations/updateWebhookSubscription.md) — `PATCH /api/v1/webhooks/subscriptions/{id}` — Update a webhook subscription (url / events / active) - [deleteWebhookSubscription](/operations/deleteWebhookSubscription.md) — `DELETE /api/v1/webhooks/subscriptions/{id}` — Delete a webhook subscription - [rotateWebhookSecret](/operations/rotateWebhookSecret.md) — `POST /api/v1/webhooks/subscriptions/{id}/rotate-secret` — Rotate a webhook subscription's signing secret - [listWebhookDeliveries](/operations/listWebhookDeliveries.md) — `GET /api/v1/webhooks/deliveries` — List recent webhook delivery attempts (the outbox) - [testWebhookSubscription](/operations/testWebhookSubscription.md) — `POST /api/v1/webhooks/subscriptions/{id}/test` — Send a signed test event to a subscription ================================================================================ # FILE: /okf/tags/traceability-audit.md ================================================================================ --- type: Reference title: Traceability & Audit description: UNTP/EPCIS supply-chain traceability events, lineage queries, and the public seal verifier. resource: https://opendpp-node.eu/api-reference tags: - api domain - traceability-audit generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- UNTP/EPCIS supply-chain traceability events, lineage queries, and the public seal verifier. The verifier checks the cryptographic seal AND that the signing workspace is bound to the economic operator declared in the payload. ## Operations - [registerTraceabilityEvent](/operations/registerTraceabilityEvent.md) — `POST /api/v1/events` — Register a UNTP/EPCIS 2.0 traceability event (VC-shaped) - [captureEpcisDocument](/operations/captureEpcisDocument.md) — `POST /api/v1/events/epcis` — Capture a native GS1 EPCIS 2.0 document (JSON/JSON-LD) - [getEventLineage](/operations/getEventLineage.md) — `GET /api/v1/events/{id}/lineage` — Retrieve the upstream pedigree of an event as a recursive lineage DAG - [verifyPassportSeal](/operations/verifyPassportSeal.md) — `POST /api/v1/audit/verify` — Publicly verify a passport's seal, certificate chain and timestamp ================================================================================ # FILE: /okf/tags/public-resolution.md ================================================================================ --- type: Reference title: Public Resolution description: "Unauthenticated, content-negotiated passport resolution: GS1 Digital Link paths, passport and unit pages." resource: https://opendpp-node.eu/api-reference tags: - api domain - public-resolution generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Unauthenticated, content-negotiated passport resolution: GS1 Digital Link paths, passport and unit pages. One URL serves JSON-LD (default), an AAS environment (`Accept: application/aas+json`), a signed UNTP Verifiable Credential (`Accept: application/vc+jwt` enveloping, `application/vc+ld+json` embedded `ecdsa-jcs-2019` Data Integrity, or `application/dc+sd-jwt` SD-JWT-VC selective disclosure; the first two also item-level on `/unit/:id`), or HTML (`Accept: text/html`). Tiered by optional credentials or grant tokens. Rate limit: 30 requests/min per IP. ## Operations - [resolvePublicPassport](/operations/resolvePublicPassport.md) — `GET /passport/{id}` — Resolve a passport by UUID (JSON-LD / AAS / HTML) - [resolveGs1Gtin](/operations/resolveGs1Gtin.md) — `GET /01/{gtin14}` — GS1 Digital Link resolution by GTIN-14 (AI 01) - [resolveGs1GtinSerial](/operations/resolveGs1GtinSerial.md) — `GET /01/{gtin14}/21/{serial}` — GS1 Digital Link serialised-item redirect (AI 01 + AI 21) - [resolveGs1Grai](/operations/resolveGs1Grai.md) — `GET /8003/{grai}` — GS1 Digital Link resolution by GRAI (AI 8003) - [resolvePublicBatteryUnit](/operations/resolvePublicBatteryUnit.md) — `GET /unit/{id}` — Resolve an individual serialised battery unit - [mintGtinCheckDigit](/operations/mintGtinCheckDigit.md) — `POST /api/v1/gs1/gtin` — Compute a GTIN check digit from a company prefix + item reference - [decodeGs1](/operations/decodeGs1.md) — `POST /api/v1/gs1/decode` — Decode GS1 scan data / element string / Digital Link into structured AIs + HRI - [decodeGs1Batch](/operations/decodeGs1Batch.md) — `POST /api/v1/gs1/decode/batch` — Batch-decode many GS1 scans / element strings / Digital Links in one request ================================================================================ # FILE: /okf/tags/verifiable-credentials.md ================================================================================ --- type: Reference title: Verifiable Credentials description: "Issuer trust endpoints that back the UNTP Verifiable Credential representations: the workspace's did:web DID document (public keys only) and its W3C Bitstring Status List for revocation." resource: https://opendpp-node.eu/api-reference tags: - api domain - verifiable-credentials generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Issuer trust endpoints that back the UNTP Verifiable Credential representations: the workspace's `did:web` DID document (public keys only) and its W3C Bitstring Status List for revocation. Unauthenticated; resolve these to verify and revocation-check any OpenDPP-issued credential. ## Operations - [getTenantDidDocument](/operations/getTenantDidDocument.md) — `GET /tenants/{tenantId}/did.json` — Resolve a tenant's did:web DID document - [getTenantRevocationStatusList](/operations/getTenantRevocationStatusList.md) — `GET /tenants/{tenantId}/status/revocation` — Tenant revocation status list (W3C Bitstring Status List) ================================================================================ # FILE: /okf/tags/schemas-vocabulary.md ================================================================================ --- type: Reference title: Schemas & Vocabulary description: "Machine-readable contracts: per-category ESPR JSON Schemas, the W3C JSON-LD context, and the curated materials vocabulary." resource: https://opendpp-node.eu/api-reference tags: - api domain - schemas-vocabulary generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Machine-readable contracts: per-category ESPR JSON Schemas, the W3C JSON-LD context, and the curated materials vocabulary. ## Operations - [getSectorSchema](/operations/getSectorSchema.md) — `GET /api/v1/schemas/{category}` — Get the ESPR metadata schema for a product category - [getDppJsonLdContext](/operations/getDppJsonLdContext.md) — `GET /contexts/dpp/v1` — Canonical resolvable JSON-LD context for passport & unit documents - [getJsonLdContext](/operations/getJsonLdContext.md) — `GET /context/v1` — W3C JSON-LD context document for passport terms (secondary, fixed term list) - [listMaterials](/operations/listMaterials.md) — `GET /api/v1/materials` — List the platform-curated material vocabulary ================================================================================ # FILE: /okf/tags/qr-codes.md ================================================================================ --- type: Reference title: QR Codes description: Export GS1-Digital-Link QR codes (PNG/SVG, 128–2048 px, GS1 quiet zone) for passports and battery units. resource: https://opendpp-node.eu/api-reference tags: - api domain - qr-codes generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Export GS1-Digital-Link QR codes (PNG/SVG, 128–2048 px, GS1 quiet zone) for passports and battery units. ## Operations - [getPassportQrCode](/operations/getPassportQrCode.md) — `GET /api/v1/passports/{id}/qr` — Export a print-grade GS1 Digital Link QR code for a passport - [bulkExportPassportLabels](/operations/bulkExportPassportLabels.md) — `POST /api/v1/passports/labels` — Bulk-export print-grade QR labels for many passports as a ZIP - [getBatteryUnitQrCode](/operations/getBatteryUnitQrCode.md) — `GET /api/v1/units/{id}/qr` — Export a print-grade QR code for an individual battery unit ================================================================================ # FILE: /okf/tags/eidas-keys.md ================================================================================ --- type: Reference title: eIDAS Keys description: Tenant signing-key management. resource: https://opendpp-node.eu/api-reference tags: - api domain - eidas-keys generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Tenant signing-key management. Keys are generated and held server-side in an encrypted vault; private key material is never returned by any endpoint. ## Operations - [rotateTenantKeys](/operations/rotateTenantKeys.md) — `POST /api/v1/tenants/rotate-keys` — Rotate the tenant's ECDSA signing key pair - [getSealCaCertificate](/operations/getSealCaCertificate.md) — `GET /.well-known/opendpp-seal-ca.pem` — Download the platform seal-CA certificate (PEM) ================================================================================ # FILE: /okf/tags/account.md ================================================================================ --- type: Reference title: Account description: "Identity of the authenticated API key / session: workspace, role, permissions, operator scope, and passport usage against the tier quota — the integration-facing counterpart to the console's profile endpoints." resource: https://opendpp-node.eu/api-reference tags: - api domain - account generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Identity of the authenticated API key / session: workspace, role, permissions, operator scope, and passport usage against the tier quota — the integration-facing counterpart to the console's profile endpoints. ## Operations - [whoami](/operations/whoami.md) — `GET /api/v1/whoami` — Identity of the authenticated key / session ================================================================================ # FILE: /okf/tags/service.md ================================================================================ --- type: Reference title: Service description: Service metadata and liveness. resource: https://opendpp-node.eu/api-reference tags: - api domain - service generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Service metadata and liveness. ## Operations - [getHealth](/operations/getHealth.md) — `GET /health` — Service health check - [getApiVersion](/operations/getApiVersion.md) — `GET /api/v1/version` — Running API contract version & build identity ================================================================================ # FILE: /okf/operations/index.md ================================================================================ # Passports * [GET /api/v1/passports](listPassports.md) - List passports in your workspace (paginated JSON-LD) * [POST /api/v1/passports](createPassport.md) - Create (ingest) a Digital Product Passport * [POST /api/v1/passports/validate-only](validatePassport.md) - Dry-run ESPR validation of passport metadata (nothing is stored) * [POST /api/v1/passports/validate-only-public](validatePassportPublic.md) - Permission-free dry-run ESPR metadata validation (strictly rate-limited) * [POST /api/v1/passports/bulk](bulkIngestPassports.md) - Bulk-ingest up to 200 passports with per-row error reporting * [POST /api/v1/passports/aas/ingest](ingestPassportFromAas.md) - Ingest a passport from an AAS JSON Environment (seal-verified) * [GET /api/v1/passports/vc-readiness](passportVcReadinessReport.md) - Catalog-wide UNTP Verifiable-Credential readiness report * [GET /api/v1/passports/{id}](getPassport.md) - Fetch a single passport (content-negotiated JSON-LD / AAS / HTML) * [PUT /api/v1/passports/{id}](updatePassport.md) - Update passport metadata (versioned to history) * [DELETE /api/v1/passports/{id}](deleteDraftPassport.md) - Permanently delete a DRAFT passport * [POST /api/v1/passports/{id}/seal](sealPassport.md) - Apply the tenant's advanced electronic seal * [PUT /api/v1/passports/{id}/status](updatePassportStatus.md) - Transition passport lifecycle status (recall / decommission / reactivate) # Economic Operators * [GET /api/v1/operators](listOperators.md) - List economic operators bound to your workspace * [POST /api/v1/operators](registerOperator.md) - Register an economic operator and bind it to your workspace * [GET /api/v1/operators/{id}](getOperator.md) - Fetch a single bound economic operator * [PATCH /api/v1/operators/{id}](updateOperator.md) - Update an operator's name or role (regId is immutable) * [DELETE /api/v1/operators/{id}](deleteOperator.md) - Remove an operator (archives if it has passports, else hard-deletes) * [POST /api/v1/operators/{id}/restore](restoreOperator.md) - Restore an archived operator and its archived passports # Battery Units * [POST /api/v1/passports/{passportId}/units/validate](validateBatteryUnits.md) - Pre-flight: validate battery-unit identifiers without persisting * [GET /api/v1/passports/{passportId}/units](listBatteryUnits.md) - List serialised battery units under a passport * [POST /api/v1/passports/{passportId}/units](serializeBatteryUnits.md) - Serialise individual battery units under a passport (bulk, up to 200) * [GET /api/v1/units/{id}](getBatteryUnit.md) - Get one battery unit as JSON-LD with its dynamic-data history * [DELETE /api/v1/units/{id}](deleteBatteryUnit.md) - Not deletable: a serialised unit is a marketed physical item (always 409) * [GET /api/v1/units/{id}/events](listBatteryUnitEvents.md) - List a battery unit's telemetry history (newest first, cursor-paginated) * [POST /api/v1/units/{id}/events](recordBatteryUnitEvent.md) - Append an immutable telemetry event to a battery unit * [POST /api/v1/units/{id}/events/bulk](bulkRecordBatteryUnitEvents.md) - Append a batch of telemetry events to a battery unit # Facilities * [GET /api/v1/facilities](listFacilities.md) - List facilities in the tenant workspace * [POST /api/v1/facilities](createFacility.md) - Register a facility (GS1 GLN) * [GET /api/v1/facilities/{id}](getFacility.md) - Get a single facility * [PUT /api/v1/facilities/{id}](updateFacility.md) - Update facility master data (GLN is immutable) * [DELETE /api/v1/facilities/{id}](deleteFacility.md) - Delete a facility (passports are unlinked, never deleted) # Access Grants * [GET /api/v1/grants](listGrants.md) - List access grants and pending access requests * [POST /api/v1/grants](createGrant.md) - Issue a legitimate-interest access grant directly * [POST /api/v1/grants/{id}/approve](approveGrantRequest.md) - Approve a pending access request and mint its token * [POST /api/v1/grants/{id}/deny](denyGrantRequest.md) - Deny a pending access request * [DELETE /api/v1/grants/{id}](revokeGrant.md) - Revoke an access grant (soft revocation) # Webhooks * [GET /api/v1/webhooks/subscriptions](listWebhookSubscriptions.md) - List webhook subscriptions (signing secrets stripped) * [POST /api/v1/webhooks/subscriptions](createWebhookSubscription.md) - Register a webhook subscription (signing secret returned once) * [PATCH /api/v1/webhooks/subscriptions/{id}](updateWebhookSubscription.md) - Update a webhook subscription (url / events / active) * [DELETE /api/v1/webhooks/subscriptions/{id}](deleteWebhookSubscription.md) - Delete a webhook subscription * [POST /api/v1/webhooks/subscriptions/{id}/rotate-secret](rotateWebhookSecret.md) - Rotate a webhook subscription's signing secret * [GET /api/v1/webhooks/deliveries](listWebhookDeliveries.md) - List recent webhook delivery attempts (the outbox) * [POST /api/v1/webhooks/subscriptions/{id}/test](testWebhookSubscription.md) - Send a signed test event to a subscription # Traceability & Audit * [POST /api/v1/events](registerTraceabilityEvent.md) - Register a UNTP/EPCIS 2.0 traceability event (VC-shaped) * [POST /api/v1/events/epcis](captureEpcisDocument.md) - Capture a native GS1 EPCIS 2.0 document (JSON/JSON-LD) * [GET /api/v1/events/{id}/lineage](getEventLineage.md) - Retrieve the upstream pedigree of an event as a recursive lineage DAG * [POST /api/v1/audit/verify](verifyPassportSeal.md) - Publicly verify a passport's seal, certificate chain and timestamp # Public Resolution * [GET /passport/{id}](resolvePublicPassport.md) - Resolve a passport by UUID (JSON-LD / AAS / HTML) * [GET /01/{gtin14}](resolveGs1Gtin.md) - GS1 Digital Link resolution by GTIN-14 (AI 01) * [GET /01/{gtin14}/21/{serial}](resolveGs1GtinSerial.md) - GS1 Digital Link serialised-item redirect (AI 01 + AI 21) * [GET /8003/{grai}](resolveGs1Grai.md) - GS1 Digital Link resolution by GRAI (AI 8003) * [GET /unit/{id}](resolvePublicBatteryUnit.md) - Resolve an individual serialised battery unit * [POST /api/v1/gs1/gtin](mintGtinCheckDigit.md) - Compute a GTIN check digit from a company prefix + item reference * [POST /api/v1/gs1/decode](decodeGs1.md) - Decode GS1 scan data / element string / Digital Link into structured AIs + HRI * [POST /api/v1/gs1/decode/batch](decodeGs1Batch.md) - Batch-decode many GS1 scans / element strings / Digital Links in one request # Verifiable Credentials * [GET /tenants/{tenantId}/did.json](getTenantDidDocument.md) - Resolve a tenant's did:web DID document * [GET /tenants/{tenantId}/status/revocation](getTenantRevocationStatusList.md) - Tenant revocation status list (W3C Bitstring Status List) # Schemas & Vocabulary * [GET /api/v1/schemas/{category}](getSectorSchema.md) - Get the ESPR metadata schema for a product category * [GET /contexts/dpp/v1](getDppJsonLdContext.md) - Canonical resolvable JSON-LD context for passport & unit documents * [GET /context/v1](getJsonLdContext.md) - W3C JSON-LD context document for passport terms (secondary, fixed term list) * [GET /api/v1/materials](listMaterials.md) - List the platform-curated material vocabulary # QR Codes * [GET /api/v1/passports/{id}/qr](getPassportQrCode.md) - Export a print-grade GS1 Digital Link QR code for a passport * [POST /api/v1/passports/labels](bulkExportPassportLabels.md) - Bulk-export print-grade QR labels for many passports as a ZIP * [GET /api/v1/units/{id}/qr](getBatteryUnitQrCode.md) - Export a print-grade QR code for an individual battery unit # eIDAS Keys * [POST /api/v1/tenants/rotate-keys](rotateTenantKeys.md) - Rotate the tenant's ECDSA signing key pair * [GET /.well-known/opendpp-seal-ca.pem](getSealCaCertificate.md) - Download the platform seal-CA certificate (PEM) # Account * [GET /api/v1/whoami](whoami.md) - Identity of the authenticated key / session # Service * [GET /health](getHealth.md) - Service health check * [GET /api/v1/version](getApiVersion.md) - Running API contract version & build identity ================================================================================ # FILE: /okf/operations/whoami.md ================================================================================ --- type: API Endpoint title: Identity of the authenticated key / session description: "Returns a compact, integration-focused view of the calling credential: the workspace, the principal's role and resolved permissions, whether the session is an API key, the operator the key is scoped to (null = workspace-wide), and active-p…" resource: https://opendpp-node.eu/api/v1/whoami tags: - GET - account generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/whoami` **Domain:** [Account](/tags/account.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Returns a compact, integration-focused view of the calling credential: the workspace, the principal's role and resolved permissions, whether the session is an API key, the operator the key is scoped to (`null` = workspace-wide), and active-passport usage against the tier quota. Use it to verify a key works, discover the effective permission set, and surface remaining quota. Profile, localization and billing details are deliberately not exposed here — this is the integration view of the credential. **Permission:** none beyond a valid tenant-scoped session — any API key can call it. Platform-admin sessions are rejected with `403` (they are not tenant-scoped). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Responses - **200** — The authenticated identity. → [WhoamiResponse](/schemas/WhoamiResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — The session is not scoped to a tenant workspace (e.g. a platform-admin session). → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/whoami' ``` ## See also Schemas: [Error](/schemas/Error.md), [WhoamiResponse](/schemas/WhoamiResponse.md). ================================================================================ # FILE: /okf/operations/validateBatteryUnits.md ================================================================================ --- type: API Endpoint title: "Pre-flight: validate battery-unit identifiers without persisting" description: NON-MUTATING pre-flight for bulk unit import. resource: https://opendpp-node.eu/api/v1/passports/{passportId}/units/validate tags: - POST - battery-units generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/passports/{passportId}/units/validate` **Domain:** [Battery Units](/tags/battery-units.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. NON-MUTATING pre-flight for bulk unit import. Runs the SAME engine-backed AI-21 / GS1 Digital Link conformance + field checks as `POST /api/v1/passports/{passportId}/units` and returns a per-item verdict — **persisting nothing**. Send a single unit or `{"units": [...]}` (≤200). Lets a bulk importer ask "would these serials be GS1-conformant?" before committing a batch. **Permission:** `battery:write` (gated as the write permission, like other validate-only checks; subscription gating → 402). **Validation:** `serialNumber` charset/length (`^[A-Za-z0-9._-]{1,20}$`, a URL-safe subset of GS1 AI-21 CSET 82) PLUS authoritative GS1-engine conformance for EVERY unit — a GTIN-keyed passport's unit Digital Link must parse cleanly through the engine, and a non-GTIN passport's AI-21 serial VALUE is validated through the same engine (CSET-82 charset + length); `status` must be a valid unit status; `manufacturedAt` must be Date-parseable. Predecessor linkage is NOT checked here (a persistence-time concern). The verdict order matches the input order. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Request body Schema (required): [SerializeBatteryUnitsRequest](/schemas/SerializeBatteryUnitsRequest.md). ```json { "units": [ { "serialNumber": "BATT-2026-000451" }, { "serialNumber": "bad serial!" } ] } ``` ## Responses - **200** — Per-item conformance verdicts in input order (nothing persisted). - **400** — Invalid body envelope (not a JSON object, empty units, or more than 200 items). → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — Passport not found under your tenant workspace. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/passports/{passportId}/units/validate' \ --data '{"units":[{"serialNumber":"BATT-2026-000451"},{"serialNumber":"bad serial!"}]}' ``` ## See also Schemas: [Error](/schemas/Error.md), [SerializeBatteryUnitsRequest](/schemas/SerializeBatteryUnitsRequest.md). ================================================================================ # FILE: /okf/operations/listBatteryUnits.md ================================================================================ --- type: API Endpoint title: List serialised battery units under a passport description: Lists all serialised units of the passport, newest first (createdAt DESC). resource: https://opendpp-node.eu/api/v1/passports/{passportId}/units tags: - GET - battery-units generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/passports/{passportId}/units` **Domain:** [Battery Units](/tags/battery-units.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Lists **all** serialised units of the passport, newest first (`createdAt` DESC). **Paginated** with `?page` (default 1) and `?limit` (default 100, max 200) — a SKU may carry many physical units; `count` is this page's size, `total`/`totalPages` describe the full set. **Permission:** `battery:read`. Operator-scoped credentials may only read passports of their own Economic Operator (403). Units are returned as stored. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `page` | query | no | integer | 1-based page number (digits only; non-numeric falls back to 1). | | `limit` | query | no | integer | Page size. | ## Responses - **200** — The passport's units. → [BatteryUnitListResponse](/schemas/BatteryUnitListResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/passports/{passportId}/units' ``` ## See also Schemas: [BatteryUnitListResponse](/schemas/BatteryUnitListResponse.md). ================================================================================ # FILE: /okf/operations/serializeBatteryUnits.md ================================================================================ --- type: API Endpoint title: Serialise individual battery units under a passport (bulk, up to 200) description: Creates one or many individual physical battery units (EU Battery Regulation) under a SKU/type-level passport. resource: https://opendpp-node.eu/api/v1/passports/{passportId}/units tags: - POST - battery-units generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/passports/{passportId}/units` **Domain:** [Battery Units](/tags/battery-units.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Creates one or many **individual physical battery units** (EU Battery Regulation) under a SKU/type-level passport. Send either a single unit object or `{"units": [...]}` with **at most 200 items** (if `units` is present and an array it is used; otherwise the whole body is treated as one unit). **Permission:** `battery:write`. Bearer API key (`op_dpp_token_…`) or session JWT; cookie-session clients must send `X-CSRF-Token`. Operator-scoped credentials may only serialise under passports of their own Economic Operator (403). Write operations pass subscription gating (402) and optional tenant MFA enforcement (403). **Per-item validation (collected as plain-string errors, not a rejection of the whole batch):** `serialNumber` is trimmed then must match `^[A-Za-z0-9._-]{1,20}$` (a URL-safe subset of GS1 AI-21 CSET 82, ≤ 20 chars) AND is validated to full AI-21 conformance by GS1's authoritative engine — a GTIN-keyed unit through its full Digital Link, a non-GTIN unit through its AI-21 serial value; `status` must be a valid unit status; `manufacturedAt` must be Date-parseable; duplicate `(passport, serialNumber)` pairs are skipped with *"A unit with this serial already exists for this passport"*. Each created unit gets a per-unit GS1 Digital Link URI `/{01|8003}/{productId}/21/{serialNumber}` carrying the **real physical serial** in AI-21. **Predecessor linkage (repurpose/remanufacture):** `predecessorUnitId` must reference an existing unit **in your tenant** (any passport). A recycled predecessor (`ceasedAt` set) is refused — its passport has ceased to exist. (A unit *created* with status `RECYCLED` is ceased from birth — `ceasedAt` is stamped at creation — and is refused as a predecessor exactly like one recycled via the events route.) In one transaction the new unit is created, an append-only `STATUS_CHANGE` event (`{status, successorUnitId, successorSerial}` payload) is written to the predecessor, and the predecessor's status is set to `predecessorStatus` (default `REPURPOSED`; only `REPURPOSED|REMANUFACTURED|REUSED` allowed). **Partial success:** the response is **201 when at least one unit was created**; skipped items are listed in `errors`. If *every* item failed you get **400 `Serialisation Failed`** with the same string array. A `batteryunit.created` audit event and a tenant notification are emitted on success. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Request body Schema (required): [SerializeBatteryUnitsRequest](/schemas/SerializeBatteryUnitsRequest.md). ```json { "units": [ { "serialNumber": "BATT-2026-000451", "manufacturedAt": "2026-05-02T08:00:00.000Z" }, { "serialNumber": "BATT-2026-000452", "status": "IN_SERVICE", "predecessorUnitId": "5a1c9e7d-3b2f-4c8a-9e6d-7f0b1a2c3d4e", "predecessorStatus": "REMANUFACTURED" } ] } ``` ## Responses - **201** — At least one unit was serialised. → [SerializeBatteryUnitsResponse](/schemas/SerializeBatteryUnitsResponse.md) - **400** — Three shapes: (1) standard Bad Request triple when the body is not a JSON object, the units array is empty, or more than 200 units are sent; (2) Serialisation… → [BatteryUnitSerialiseBadRequest](/schemas/BatteryUnitSerialiseBadRequest.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/passports/{passportId}/units' \ --data '{"units":[{"serialNumber":"BATT-2026-000451","manufacturedAt":"2026-05-02T08:00:00.000Z"},{"serialNumber":"BATT-2026-000452","status":"IN_SERVICE","predecessorUnitId":"5a1c9e7d-3b2f-4c8a-9e6d-7f0b1a2c3d4e","predecessorStatus":"REMANUFACTURED"}]}' ``` ## See also Schemas: [BatteryUnitSerialiseBadRequest](/schemas/BatteryUnitSerialiseBadRequest.md), [SerializeBatteryUnitsRequest](/schemas/SerializeBatteryUnitsRequest.md), [SerializeBatteryUnitsResponse](/schemas/SerializeBatteryUnitsResponse.md). ================================================================================ # FILE: /okf/operations/getBatteryUnit.md ================================================================================ --- type: API Endpoint title: Get one battery unit as JSON-LD with its dynamic-data history description: "Returns the unit as a JSON-LD document (Content-Type: application/ld+json) in the privileged tenant view: currentState (the latest telemetry snapshot) and dynamicData (the 500 most recent events, newest first by recordedAt) are included; t…" resource: https://opendpp-node.eu/api/v1/units/{id} tags: - GET - battery-units generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/units/{id}` **Domain:** [Battery Units](/tags/battery-units.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Returns the unit as a **JSON-LD document** (`Content-Type: application/ld+json`) in the **privileged tenant view**: `currentState` (the latest telemetry snapshot) and `dynamicData` (the **500 most recent** events, newest first by `recordedAt`) are included; the public `restrictedData` marker is absent. The embedded `ofModel` is the SKU/type passport document rendered in the **owner (unredacted) variant** — legitimate-interest-tier metadata and owner-only keys are NOT masked, unlike the anonymous public document. **Caveat:** this authenticated endpoint does **not** load lineage relations, so `repurposedFrom` is always `null` and `successorUnits` is always `[]` here even when lineage exists; the public resolver view (`GET /unit/{id}`) does resolve them. **Permission:** `battery:read`. Operator-scoped credentials may only read units whose passport belongs to their Economic Operator (403). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Responses - **200** — The unit's JSON-LD document (privileged view, telemetry included). → [BatteryUnitJsonLd](/schemas/BatteryUnitJsonLd.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/units/{id}' ``` ## See also Schemas: [BatteryUnitJsonLd](/schemas/BatteryUnitJsonLd.md). ================================================================================ # FILE: /okf/operations/deleteBatteryUnit.md ================================================================================ --- type: API Endpoint title: "Not deletable: a serialised unit is a marketed physical item (always 409)" description: Always refused with 409. resource: https://opendpp-node.eu/api/v1/units/{id} tags: - DELETE - battery-units generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `DELETE /api/v1/units/{id}` **Domain:** [Battery Units](/tags/battery-units.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. **Always refused with 409.** A serialised unit is an item-level battery passport for a physical battery placed on the market, so the record — including its append-only telemetry — is retained (EU Battery Regulation persistence, mirroring the passport-level archive model). End a unit's life through the lifecycle instead: append a `STATUS_CHANGE` event via `POST /api/v1/units/{id}/events` — `RECYCLED` ceases it (public 410 tombstone), `DECOMMISSIONED` retires it. Hard removal is reserved for the node's retention-gated purge, never an ad-hoc API delete. **Permission:** `battery:write`. Cookie-session clients must send `X-CSRF-Token`. Operator-scoped credentials may only address units whose passport belongs to their Economic Operator (403). Write operations pass subscription gating (402) and optional tenant MFA enforcement (403). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Responses - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **409** — Always, for an existing unit under your workspace — the unit represents a marketed physical item and cannot be deleted; its record and telemetry are retained. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X DELETE 'https://opendpp-node.eu/api/v1/units/{id}' ``` ## See also Schemas: [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/listBatteryUnitEvents.md ================================================================================ --- type: API Endpoint title: List a battery unit's telemetry history (newest first, cursor-paginated) description: Returns one page of the unit's append-only dynamic-data history ordered by recordedAt DESC, ties broken by id DESC — so paging is deterministic. resource: https://opendpp-node.eu/api/v1/units/{id}/events tags: - GET - battery-units generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/units/{id}/events` **Domain:** [Battery Units](/tags/battery-units.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Returns one page of the unit's append-only dynamic-data history ordered by `recordedAt` DESC, ties broken by `id` DESC — so paging is deterministic. A page holds at most 500 events (`limit`, default 500); while older history remains the response carries a non-null `nextCursor` — pass it back as `cursor` to fetch the next (older) page, so the **full history is retrievable** however long it grows. The cursor is opaque; a malformed value returns **400**. **Permission:** `battery:read`. Operator-scoped credentials may only read units whose passport belongs to their Economic Operator (403). Events are returned as stored. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `limit` | query | no | integer | Page size (1–500). | | `cursor` | query | no | string | Opaque page cursor — the nextCursor value from the previous page. | ## Responses - **200** — One page of the unit's telemetry history. → [BatteryUnitEventListResponse](/schemas/BatteryUnitEventListResponse.md) - **400** — Malformed cursor, or limit outside 1–500. → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/units/{id}/events' ``` ## See also Schemas: [BatteryUnitEventListResponse](/schemas/BatteryUnitEventListResponse.md), [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/recordBatteryUnitEvent.md ================================================================================ --- type: API Endpoint title: Append an immutable telemetry event to a battery unit description: "Appends one append-only per-unit dynamic-data record (Annex XIII / Art. 77: SoH, cycle count, remaining capacity, temperature, negative events)." resource: https://opendpp-node.eu/api/v1/units/{id}/events tags: - POST - battery-units generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/units/{id}/events` **Domain:** [Battery Units](/tags/battery-units.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Appends one **append-only** per-unit dynamic-data record (Annex XIII / Art. 77: SoH, cycle count, remaining capacity, temperature, negative events). History is immutable — there is **no update or delete path** for events. **Permission:** `battery:write`. Cookie-session clients must send `X-CSRF-Token`. Operator-scoped credentials may only write to units whose passport belongs to their Economic Operator (403). Write operations pass subscription gating (402) and optional tenant MFA enforcement (403). **Validation (400 with the standard error triple):** `eventType` is required and must be one of `SOH_MEASUREMENT|CHARGE_CYCLE|STATUS_CHANGE|NEGATIVE_EVENT|OTHER`; `stateOfHealth` 0–100; `cycleCount` and `remainingCapacityAh` 0–9007199254740991; `temperatureC` −273.15–10000 (each may also be `null`/omitted); `status`, if present, must be a valid unit status; `recordedAt` must be Date-parseable (defaults to server time when omitted). `cycleCount` is truncated to an integer before persisting; a `payload` that is not an object or array is silently dropped (stored as `null`) — JSON **arrays** pass the server's `typeof` check and are persisted verbatim. **Status transition:** when `status` is present and differs from the unit's current status, the unit is updated **in the same transaction** as the event — this works with *any* `eventType`, though `STATUS_CHANGE` is the conventional carrier. Transitioning to **`RECYCLED`** additionally stamps `ceasedAt` (if not already set; never cleared), after which the public unit view becomes a 410 tombstone and the unit can no longer gain successor units. `RECYCLED` is terminal: once the unit's status is `RECYCLED` this endpoint refuses **every** further event with **400** `Terminal Unit Status` — neither `status` nor telemetry can change again. A second life must be linked with `predecessorUnitId` **before** the predecessor is recycled — a terminal unit is itself refused as a `predecessorUnitId`, so there is no path back once it is recycled. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `Idempotency-Key` | header | no | string | Optional client idempotency key (≤255 characters, no control characters). | ## Request body Schema (required): [RecordBatteryUnitEventRequest](/schemas/RecordBatteryUnitEventRequest.md). ```json { "eventType": "SOH_MEASUREMENT", "stateOfHealth": 96.8, "cycleCount": 140, "remainingCapacityAh": 48.2, "temperatureC": 24.5, "payload": { "measuredBy": "BMS firmware 4.2.1" }, "recordedAt": "2026-06-12T09:41:00.000Z" } ``` ## Responses - **201** — Event appended (and, when status was supplied and differed, the unit's status transitioned in the same transaction). → [RecordBatteryUnitEventResponse](/schemas/RecordBatteryUnitEventResponse.md) - **400** — Two shapes: (1) the standard error triple from handler validation — messages: Request body must be a valid JSON object; eventType must be one of: SOH_MEASUREME… → [BatteryUnitEventBadRequest](/schemas/BatteryUnitEventBadRequest.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — The transaction failed. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/units/{id}/events' \ --data '{"eventType":"SOH_MEASUREMENT","stateOfHealth":96.8,"cycleCount":140,"remainingCapacityAh":48.2,"temperatureC":24.5,"payload":{"measuredBy":"BMS firmware 4.2.1"},"recordedAt":"2026-06-12T09:41:00.000Z"}' ``` ## See also Schemas: [BatteryUnitEventBadRequest](/schemas/BatteryUnitEventBadRequest.md), [Error](/schemas/Error.md), [RecordBatteryUnitEventRequest](/schemas/RecordBatteryUnitEventRequest.md), [RecordBatteryUnitEventResponse](/schemas/RecordBatteryUnitEventResponse.md). ================================================================================ # FILE: /okf/operations/bulkRecordBatteryUnitEvents.md ================================================================================ --- type: API Endpoint title: Append a batch of telemetry events to a battery unit description: Appends up to 500 append-only dynamic-data records to one unit in a single request — the batch venue for backfilling a fleet's telemetry. resource: https://opendpp-node.eu/api/v1/units/{id}/events/bulk tags: - POST - battery-units generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/units/{id}/events/bulk` **Domain:** [Battery Units](/tags/battery-units.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Appends up to **500** append-only dynamic-data records to one unit in a single request — the batch venue for backfilling a fleet's telemetry. **Telemetry only:** a record carrying `status` is refused per-item; a status transition is a lifecycle decision and goes through `POST /api/v1/units/{id}/events` one event at a time. **Permission:** `battery:write`. Cookie-session clients must send `X-CSRF-Token`. Operator-scoped credentials may only write to units whose passport belongs to their Economic Operator (403). Write operations pass subscription gating (402) and optional tenant MFA enforcement (403). A terminal (`RECYCLED`) unit refuses the whole batch (400 `Terminal Unit Status`). **Per-record validation (collected as `[index]`-prefixed strings in `errors`, not a rejection of the whole batch):** the same field checks as the single-event endpoint — `eventType` required and valid, numeric ranges, Date-parseable `recordedAt` (defaults to server time when omitted) — plus the physics consistency checks, judged in chronological order across the batch and the unit's recorded history, so a reading that only conflicts with another batch member is caught too. **Partial success:** the response is **201 when at least one record was accepted**; skipped items are listed in `errors`. If *every* item failed you get **400** `Bulk Event Ingest Failed` with the same string array. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `Idempotency-Key` | header | no | string | Optional client idempotency key (≤255 characters, no control characters). | ## Request body Schema (required): [BulkBatteryUnitEventsRequest](/schemas/BulkBatteryUnitEventsRequest.md). ```json { "events": [ { "eventType": "SOH_MEASUREMENT", "stateOfHealth": 96.8, "cycleCount": 140, "recordedAt": "2026-06-12T09:41:00.000Z" }, { "eventType": "CHARGE_CYCLE", "cycleCount": 141, "recordedAt": "2026-06-13T18:05:00.000Z" } ] } ``` ## Responses - **201** — At least one record was accepted. → [BulkBatteryUnitEventsResponse](/schemas/BulkBatteryUnitEventsResponse.md) - **400** — Invalid body envelope (missing/empty events, more than 500 items, malformed Idempotency-Key), a terminal unit (Terminal Unit Status), or every record failed (B… → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/units/{id}/events/bulk' \ --data '{"events":[{"eventType":"SOH_MEASUREMENT","stateOfHealth":96.8,"cycleCount":140,"recordedAt":"2026-06-12T09:41:00.000Z"},{"eventType":"CHARGE_CYCLE","cycleCount":141,"recordedAt":"2026-06-13T18:05:00.000Z"}]}' ``` ## See also Schemas: [BulkBatteryUnitEventsRequest](/schemas/BulkBatteryUnitEventsRequest.md), [BulkBatteryUnitEventsResponse](/schemas/BulkBatteryUnitEventsResponse.md), [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/listFacilities.md ================================================================================ --- type: API Endpoint title: List facilities in the tenant workspace description: Lists all facilities registered under your tenant workspace, sorted by createdAt descending. resource: https://opendpp-node.eu/api/v1/facilities tags: - GET - facilities generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/facilities` **Domain:** [Facilities](/tags/facilities.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Lists all facilities registered under your tenant workspace, sorted by `createdAt` descending. **Paginated** with `?page` (default 1) and `?limit` (default 100, max 200); `count` is this page's size, `total`/`totalPages` describe the full set. A non-numeric `page`/`limit` falls back to its default. **Permission:** `facility:read` (Bearer API key or session JWT/cookie). **Operator-scoped keys:** when authenticated with an API key scoped to an Economic Operator, the list contains only facilities whose `operatorId` equals the key's operator — facilities with no operator (`operatorId: null`) are **excluded** from the list (they remain readable individually via `GET /api/v1/facilities/{id}`). The full row is returned to the owner, including the privileged address fields (`streetAddress`, `city`, `postalCode`) that public passport documents never expose (owner-only in JSON-LD; never emitted in AAS). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `page` | query | no | integer | 1-based page number (digits only; non-numeric falls back to 1). | | `limit` | query | no | integer | Page size. | ## Responses - **200** — Facility list. → [FacilityListEnvelope](/schemas/FacilityListEnvelope.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/facilities' ``` ## See also Schemas: [FacilityListEnvelope](/schemas/FacilityListEnvelope.md). ================================================================================ # FILE: /okf/operations/createFacility.md ================================================================================ --- type: API Endpoint title: Register a facility (GS1 GLN) description: Registers a manufacturing/processing facility as tenant-scoped master data, backing the Unique Facility Identifier (UFI, EN 18219). resource: https://opendpp-node.eu/api/v1/facilities tags: - POST - facilities generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/facilities` **Domain:** [Facilities](/tags/facilities.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Registers a manufacturing/processing facility as tenant-scoped master data, backing the Unique Facility Identifier (UFI, EN 18219). Passports reference facilities via `facilityId`. **Permission:** `facility:write`. Authenticate with a Bearer API key (`op_dpp_token_…`) or a session JWT; cookie-authenticated sessions must also send the `X-CSRF-Token` header (double-submit against the `opendpp_csrf` cookie) — Bearer clients are exempt. Write permissions are subscription-gated: a lapsed workspace subscription returns **402**. **GLN validation:** `gln` is trimmed, then must be exactly 13 digits with a valid GS1 modulo-10 check digit (same weighting algorithm as GTIN). The GLN is unique **platform-wide** (database unique constraint), so a duplicate returns **409** even if the existing facility belongs to another tenant. **Country:** `country` must match `^[A-Za-z]{2}$` after trimming and is stored uppercased. **Operator binding:** if `operatorId` is supplied (non-empty), that Economic Operator must be bound to your tenant workspace, otherwise **403**. An empty/whitespace `operatorId` is stored as `null`. Requests authenticated with an **operator-scoped API key** may only attach facilities to their own operator: a mismatched `operatorId` returns **403**, and when omitted the key's operator id is applied automatically. `activity`, `streetAddress`, `city` and `postalCode` are trimmed; empty/whitespace values are stored as `null`. **Public/privileged field split:** the public **JSON-LD** passport document exposes `id`, `gln`, `name`, `activity` and `country` of a linked facility; the public **AAS** export emits only the GLN, name and country (`manufacturingFacilityGln` / `manufacturingFacilityName` / `manufacturingFacilityCountry`, plus the GLN as a `urn:gs1:gln:` global asset reference) — the facility `id` and `activity` are never emitted in AAS. `streetAddress`, `city` and `postalCode` are owner-only in both formats. This endpoint returns the full row to you as the owner. Emits a `facility.created` audit event and an in-app notification. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Request body Schema (required): [FacilityCreateRequest](/schemas/FacilityCreateRequest.md). ```json { "gln": "0950110153014", "name": "Munich Cell Assembly Plant", "activity": "Cell assembly", "streetAddress": "Werkstrasse 12", "city": "Munich", "postalCode": "80331", "country": "DE", "operatorId": "4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b" } ``` ## Responses - **201** — Facility registered. → [FacilityCreatedEnvelope](/schemas/FacilityCreatedEnvelope.md) - **400** — Invalid request body. → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Forbidden. → [Error](/schemas/Error.md) - **409** — A facility with this GLN is already registered. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Internal error (standard envelope), with the message Failed to register facility for unexpected database errors; a failure inside the auth layer returns messag… → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/facilities' \ --data '{"gln":"0950110153014","name":"Munich Cell Assembly Plant","activity":"Cell assembly","streetAddress":"Werkstrasse 12","city":"Munich","postalCode":"80331","country":"DE","operatorId":"4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b"}' ``` ## See also Schemas: [Error](/schemas/Error.md), [FacilityCreateRequest](/schemas/FacilityCreateRequest.md), [FacilityCreatedEnvelope](/schemas/FacilityCreatedEnvelope.md). ================================================================================ # FILE: /okf/operations/getFacility.md ================================================================================ --- type: API Endpoint title: Get a single facility description: Fetches one facility by id, scoped to your tenant workspace. resource: https://opendpp-node.eu/api/v1/facilities/{id} tags: - GET - facilities generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/facilities/{id}` **Domain:** [Facilities](/tags/facilities.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Fetches one facility by id, scoped to your tenant workspace. **Permission:** `facility:read`. **Operator-scoped keys:** if the facility belongs to a *different* Economic Operator than the key's scope, the response is **403**. Facilities with no operator (`operatorId: null`) **are** readable by operator-scoped keys here, even though they are excluded from the list endpoint. Returns the full row including the privileged address fields (`streetAddress`, `city`, `postalCode`) that public passport documents never expose. (Public exposure of a linked facility: the JSON-LD document shows `id`/`gln`/`name`/`activity`/`country`; the AAS export only the GLN, name and country.) **404 body:** standard envelope with message `Facility not found under your Tenant workspace`. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Responses - **200** — Facility found. → [FacilityEnvelope](/schemas/FacilityEnvelope.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Forbidden. → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/facilities/{id}' ``` ## See also Schemas: [Error](/schemas/Error.md), [FacilityEnvelope](/schemas/FacilityEnvelope.md). ================================================================================ # FILE: /okf/operations/updateFacility.md ================================================================================ --- type: API Endpoint title: Update facility master data (GLN is immutable) description: Partially updates a facility's master data. resource: https://opendpp-node.eu/api/v1/facilities/{id} tags: - PUT - facilities generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `PUT /api/v1/facilities/{id}` **Domain:** [Facilities](/tags/facilities.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Partially updates a facility's master data. **The GLN itself is immutable** — it is the resolvable UFI identifier; a `gln` key in the body is silently ignored (as is `operatorId` — the operator binding cannot be changed here). **Permission:** `facility:write`. Cookie sessions must send `X-CSRF-Token`; write permissions are subscription-gated (**402** when lapsed). **Field semantics (all optional):** - `name` — applied only when a non-empty string; an empty/whitespace or non-string value is silently ignored (`name` can never be cleared). - `activity`, `streetAddress`, `city`, `postalCode` — applied whenever the key is *present* in the body: the value is stringified and trimmed; anything that trims to empty (`null`, `""`, or a whitespace-only string) **clears the field to null** — the same normalization as POST. - `country` — when present as a string it must match `^[A-Za-z]{2}$` (else **400**) and is stored uppercased; a non-string value is silently ignored. An empty body (or one with no recognized fields) is accepted: the response is **200** with the otherwise-unchanged row, though `updatedAt` is still bumped. **Operator-scoped keys:** updating a facility that belongs to a different Economic Operator returns **403**; facilities with `operatorId: null` are updatable. Emits a `facility.updated` audit event recording the changed fields. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Request body Schema: [FacilityUpdateRequest](/schemas/FacilityUpdateRequest.md). ```json { "name": "Munich Cell Assembly Plant — Hall B", "activity": "Final manufacturing", "streetAddress": "Werkstrasse 14", "country": "DE" } ``` ## Responses - **200** — Updated facility (full row). → [FacilityEnvelope](/schemas/FacilityEnvelope.md) - **400** — country was present as a string but is not a 2-letter ISO code. → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Forbidden. → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X PUT 'https://opendpp-node.eu/api/v1/facilities/{id}' \ --data '{"name":"Munich Cell Assembly Plant — Hall B","activity":"Final manufacturing","streetAddress":"Werkstrasse 14","country":"DE"}' ``` ## See also Schemas: [Error](/schemas/Error.md), [FacilityEnvelope](/schemas/FacilityEnvelope.md), [FacilityUpdateRequest](/schemas/FacilityUpdateRequest.md). ================================================================================ # FILE: /okf/operations/deleteFacility.md ================================================================================ --- type: API Endpoint title: Delete a facility (passports are unlinked, never deleted) description: Removes the facility master-data row. resource: https://opendpp-node.eu/api/v1/facilities/{id} tags: - DELETE - facilities generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `DELETE /api/v1/facilities/{id}` **Domain:** [Facilities](/tags/facilities.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Removes the facility master-data row. **Passports are never deleted by this operation**: `Passport.facilityId` is a `SET NULL` foreign key, so any passports referencing the facility simply lose their UFI link (`facilityId` becomes `null`) and remain fully intact and publicly resolvable. **Permission:** `facility:write`. Cookie sessions must send `X-CSRF-Token`; write permissions are subscription-gated (**402** when lapsed). **Operator-scoped keys:** deleting a facility that belongs to a different Economic Operator returns **403**; facilities with `operatorId: null` are deletable. Emits a `facility.deleted` audit event and an in-app notification. **404 body:** standard envelope with message `Facility not found under your Tenant workspace`. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Responses - **200** — Facility deleted. → [FacilityDeletedEnvelope](/schemas/FacilityDeletedEnvelope.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Forbidden. → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X DELETE 'https://opendpp-node.eu/api/v1/facilities/{id}' ``` ## See also Schemas: [Error](/schemas/Error.md), [FacilityDeletedEnvelope](/schemas/FacilityDeletedEnvelope.md). ================================================================================ # FILE: /okf/operations/listGrants.md ================================================================================ --- type: API Endpoint title: List access grants and pending access requests description: "Lists the workspace's access grants — capability-token grants for the Battery Regulation's restricted data tiers (Annex XIII(2)–(4)) — including undecided third-party access requests (status: PENDING, issuerType: REQUEST) submitted via the…" resource: https://opendpp-node.eu/api/v1/grants tags: - GET - access-grants generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/grants` **Domain:** [Access Grants](/tags/access-grants.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Lists the workspace's access grants — capability-token grants for the Battery Regulation's restricted data tiers (Annex XIII(2)–(4)) — including undecided third-party access **requests** (`status: PENDING`, `issuerType: REQUEST`) submitted via the hosted request-access page. **Permission:** `grant:read`. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. Paginated with `?page` (default 1) and `?limit` (default 100, max 200), grouped by `status` ascending (alphabetical: `ACTIVE`, `DENIED`, `PENDING`, `REVOKED`) and newest-first within each group. `AUTHORITY` grants (platform-issued market-surveillance access) are listed for transparency but are not tenant-revocable (`revocable: false`). Raw capability tokens are never included — only issuance/approval responses contain them, once. **Pagination:** results are paged with `?page` (default 1) and `?limit` (default 100, max 200). The response now also carries `success`, `count`, `total` and `totalPages` alongside `grants`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `page` | query | no | integer | 1-based page number (digits only; non-numeric falls back to 1). | | `limit` | query | no | integer | Page size. | ## Responses - **200** — The workspace's grants and requests, paginated newest-first — a { success, count, page, limit, total, totalPages, grants } envelope. → [GrantListResponse](/schemas/GrantListResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/grants' ``` ## See also Schemas: [GrantListResponse](/schemas/GrantListResponse.md). ================================================================================ # FILE: /okf/operations/createGrant.md ================================================================================ --- type: API Endpoint title: Issue a legitimate-interest access grant directly description: Directly issues an ACTIVE legitimate-interest access grant (no pending request involved) and mints its capability token. resource: https://opendpp-node.eu/api/v1/grants tags: - POST - access-grants generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/grants` **Domain:** [Access Grants](/tags/access-grants.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Directly issues an `ACTIVE` legitimate-interest access grant (no pending request involved) and mints its capability token. The raw token (`dpp_li_` + 32 hex characters) is returned **once** in this response; only its SHA-256 hash is stored. The grantee presents it to the public resolution endpoints as `Authorization: Bearer dpp_li_…` or `?grant=dpp_li_…` to unlock the restricted (tier-2 / per-unit) data of the granted scope. **Permission:** `grant:write` (write operations are subject to subscription gating, so 402 is possible). Cookie-session clients must send the `X-CSRF-Token` header; Bearer clients are exempt. On workspaces that enforce multi-factor authentication, user sessions that did not authenticate with a second factor receive 403 on writes (API-key clients are exempt). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. Scope semantics: - `UNIT` — `batteryUnitId` is required; the unit must belong to this workspace. The unit's parent `passportId` is recorded on the grant. - `PASSPORT` — `passportId` is required; the passport must belong to this workspace and must not be a `DRAFT` (drafts return 404). - `TENANT` — workspace-wide; no target id needed. `expiresAt` is required, must be in the future, and at most **366 days** out. This endpoint always mints `kind: LEGITIMATE_INTEREST` — `AUTHORITY` (`dpp_auth_…`) grants are platform-issued only and cannot be created here. The issuance is audited as `grant.issued`. String fields longer than their documented maximum are **silently truncated**, not rejected; unknown fields are ignored. ## Request body Schema (required): [CreateGrantRequest](/schemas/CreateGrantRequest.md). ```json { "granteeName": "Dr. Elena Varga", "granteeEmail": "e.varga@inspection.example", "organization": "EU Battery Inspection Services", "purpose": "State-of-health verification for second-life suitability assessment under Art. 77(9).", "scopeType": "UNIT", "batteryUnitId": "7c3a91d5-2e4f-4b6a-8c0d-1e2f3a4b5c6d", "expiresAt": "2026-09-12T09:41:00.000Z" } ``` ## Responses - **201** — Grant issued. → [GrantIssuedResponse](/schemas/GrantIssuedResponse.md) - **400** — Validation failure. → [GrantRouteError](/schemas/GrantRouteError.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — For scopeType UNIT/PASSPORT: the target id does not exist in this workspace (cross-tenant targets and DRAFT passports are indistinguishable from missing ones). → [GrantRouteError](/schemas/GrantRouteError.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/grants' \ --data '{"granteeName":"Dr. Elena Varga","granteeEmail":"e.varga@inspection.example","organization":"EU Battery Inspection Services","purpose":"State-of-health verification for second-life suitability assessment under Art. 77(9).","scopeType":"UNIT","batteryUnitId":"7c3a91d5-2e4f-4b6a-8c0d-1e2f3a4b5c6d","expiresAt":"2026-09-12T09:41:00.000Z"}' ``` ## See also Schemas: [CreateGrantRequest](/schemas/CreateGrantRequest.md), [GrantIssuedResponse](/schemas/GrantIssuedResponse.md), [GrantRouteError](/schemas/GrantRouteError.md). ================================================================================ # FILE: /okf/operations/approveGrantRequest.md ================================================================================ --- type: API Endpoint title: Approve a pending access request and mint its token description: Approves a PENDING third-party access request (submitted via the hosted request-access page). resource: https://opendpp-node.eu/api/v1/grants/{id}/approve tags: - POST - access-grants generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/grants/{id}/approve` **Domain:** [Access Grants](/tags/access-grants.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Approves a `PENDING` third-party access request (submitted via the hosted request-access page). Approval mints the legitimate-interest capability token **at this moment** — pending requests carry no token — sets `status: ACTIVE`, records `decidedAt`/`decidedBy`, and replaces the request's provisional 90-day expiry with the `expiresAt` you supply (required; future; max **366 days** out). The raw token is returned **once** in this response. If the request has a `granteeEmail`, the grantee is additionally e-mailed an inspection link containing the token (`…/unit/{batteryUnitId}?grant=dpp_li_…` or `…/passport/{passportId}?grant=dpp_li_…`) — the only other place the raw token ever exists. The decision is audited as `grant.approved`. **Permission:** `grant:write` (subscription gating ⇒ 402 possible; cookie sessions need `X-CSRF-Token`; on workspaces enforcing multi-factor authentication, user sessions without a second factor get 403 — API-key clients exempt). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | The access-request (AccessGrant) id. | ## Request body Schema (required): [ApproveGrantRequest](/schemas/ApproveGrantRequest.md). ```json { "expiresAt": "2026-09-12T09:41:00.000Z" } ``` ## Responses - **200** — Request approved; the capability token is shown only here (and in the grantee e-mail). → [GrantIssuedResponse](/schemas/GrantIssuedResponse.md) - **400** — Invalid expiresAt. → [GrantRouteError](/schemas/GrantRouteError.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — No grant with this id exists in this workspace. → [GrantRouteError](/schemas/GrantRouteError.md) - **409** — The grant is not PENDING (already decided, active, or revoked). → [GrantRouteError](/schemas/GrantRouteError.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/grants/{id}/approve' \ --data '{"expiresAt":"2026-09-12T09:41:00.000Z"}' ``` ## See also Schemas: [ApproveGrantRequest](/schemas/ApproveGrantRequest.md), [GrantIssuedResponse](/schemas/GrantIssuedResponse.md), [GrantRouteError](/schemas/GrantRouteError.md). ================================================================================ # FILE: /okf/operations/denyGrantRequest.md ================================================================================ --- type: API Endpoint title: Deny a pending access request description: "Denies a PENDING third-party access request: sets status: DENIED and records decidedAt/decidedBy." resource: https://opendpp-node.eu/api/v1/grants/{id}/deny tags: - POST - access-grants generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/grants/{id}/deny` **Domain:** [Access Grants](/tags/access-grants.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Denies a `PENDING` third-party access request: sets `status: DENIED` and records `decidedAt`/`decidedBy`. No token is ever minted for a denied request, and no e-mail is sent to the requester. The decision is audited as `grant.denied`. The request body, if any, is ignored. **Permission:** `grant:write` (subscription gating ⇒ 402 possible; cookie sessions need `X-CSRF-Token`; on workspaces enforcing multi-factor authentication, user sessions without a second factor get 403 — API-key clients exempt). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | The access-request (AccessGrant) id. | ## Responses - **200** — Request denied. → [GrantDecisionResponse](/schemas/GrantDecisionResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — No grant with this id exists in this workspace. → [GrantRouteError](/schemas/GrantRouteError.md) - **409** — The grant is not PENDING (already decided, active, or revoked). → [GrantRouteError](/schemas/GrantRouteError.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X POST 'https://opendpp-node.eu/api/v1/grants/{id}/deny' ``` ## See also Schemas: [GrantDecisionResponse](/schemas/GrantDecisionResponse.md), [GrantRouteError](/schemas/GrantRouteError.md). ================================================================================ # FILE: /okf/operations/revokeGrant.md ================================================================================ --- type: API Endpoint title: Revoke an access grant (soft revocation) description: "Soft-revokes a grant: sets status: REVOKED and revokedAt (the row is retained for audit; the public resolvers reject the token from then on)." resource: https://opendpp-node.eu/api/v1/grants/{id} tags: - DELETE - access-grants generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `DELETE /api/v1/grants/{id}` **Domain:** [Access Grants](/tags/access-grants.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Soft-revokes a grant: sets `status: REVOKED` and `revokedAt` (the row is retained for audit; the public resolvers reject the token from then on). Audited as `grant.revoked`. Behavioral caveats (no status precondition — only the kind is checked): - Works on a grant in **any** status: revoking a `PENDING` request withdraws it; revoking a `DENIED` grant flips it to `REVOKED`. - Re-revoking an already-`REVOKED` grant returns 200 again and preserves the original `revokedAt`. - `AUTHORITY` grants (`kind: AUTHORITY`, platform-issued market-surveillance access) are **not tenant-revocable** — 403. Battery Reg. Art. 77 market-surveillance access must not depend on manufacturer consent; platform admins manage those. **Permission:** `grant:write` (subscription gating ⇒ 402 possible; cookie sessions need `X-CSRF-Token`; on workspaces enforcing multi-factor authentication, user sessions without a second factor get 403 — API-key clients exempt). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | The grant (AccessGrant) id. | ## Responses - **200** — Grant revoked (idempotent: re-revoking keeps the original revokedAt). → [GrantDecisionResponse](/schemas/GrantDecisionResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Two distinct bodies share this status: (1) route-level — the grant is an AUTHORITY grant and cannot be revoked by the workspace; body is {error, message} witho… → [GrantRevokeForbidden](/schemas/GrantRevokeForbidden.md) - **404** — No grant with this id exists in this workspace. → [GrantRouteError](/schemas/GrantRouteError.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X DELETE 'https://opendpp-node.eu/api/v1/grants/{id}' ``` ## See also Schemas: [GrantDecisionResponse](/schemas/GrantDecisionResponse.md), [GrantRevokeForbidden](/schemas/GrantRevokeForbidden.md), [GrantRouteError](/schemas/GrantRouteError.md). ================================================================================ # FILE: /okf/operations/listOperators.md ================================================================================ --- type: API Endpoint title: List economic operators bound to your workspace description: Returns the economic operators bound to your workspace, ordered by name. resource: https://opendpp-node.eu/api/v1/operators tags: - GET - economic-operators generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/operators` **Domain:** [Economic Operators](/tags/economic-operators.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Returns the economic operators bound to your workspace, ordered by name. Active operators only unless `?archived=true` is passed (archived operators are off-boarded but their passports are retained and still publicly resolvable). Each entry is the same `OperatorRow` shape returned by `POST`/`PATCH /api/v1/operators` — use the `id` to attribute a passport (`operatorId` on `POST /api/v1/passports`) or to address `PATCH`/`DELETE`. **Permission:** `operator:read`. Requests authenticated with an **operator-scoped API key** see only their own operator. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `archived` | query | no | string | Set true to include archived (off-boarded) operators. | ## Responses - **200** — The bound operators. → [OperatorListResponse](/schemas/OperatorListResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/operators' ``` ## See also Schemas: [OperatorListResponse](/schemas/OperatorListResponse.md). ================================================================================ # FILE: /okf/operations/registerOperator.md ================================================================================ --- type: API Endpoint title: Register an economic operator and bind it to your workspace description: Registers an economic operator (manufacturer, importer, supplier, …) and binds it to your workspace. resource: https://opendpp-node.eu/api/v1/operators tags: - POST - economic-operators generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/operators` **Domain:** [Economic Operators](/tags/economic-operators.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Registers an economic operator (manufacturer, importer, supplier, …) and binds it to your workspace. **Permission:** `operator:create`. Cookie-session clients must send the `X-CSRF-Token` header (double-submit); Bearer clients (API key / JWT) are exempt. **Deduplication (per workspace):** operators are scoped to your workspace — `regId` is unique *within* your workspace, not across the platform. If **your workspace** already has an operator with the submitted `regId`, that existing record is returned and the submitted `name`, `role` and `regIdScheme` are **ignored**. A `regId` already used by *another* workspace is irrelevant — you always get **your own** operator row (so one workspace can never bind to, rename, or archive another's operator). The call is idempotent: re-registering an already-bound operator succeeds with `201` again. The per-workspace match includes **archived** operators: if your workspace's operator for that `regId` is archived, the archived record is returned as-is (`archivedAt` non-null) with `201` — registration does not un-archive it; use `POST /api/v1/operators/{id}/restore` to reactivate it. **Registration-id integrity:** fabricated `EORI-MOCK…` ids are rejected on every path. When `regIdScheme` is `EORI`, `regId` must match `^[A-Z]{2}[A-Za-z0-9]{1,15}$` (2-letter ISO 3166 country prefix followed by up to 15 alphanumerics, e.g. `DE1234567890`). Validation is syntax-only by default. When the node operator enables the OPT-IN EORI existence check, a declared `EORI` `regId` is additionally checked for EXISTENCE against the EU Commission EOS validation service and, if not found, a NON-BLOCKING advisory is added to the 201 `warnings[]` — the operator is still registered (best-effort, fail-open: a network error, or a freshly-issued / GB EORI, never blocks registration). With the check off, `warnings` is `[]`. Side effects: an `operator.created` audit event and an in-app notification are recorded. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Request body Schema (required): [RegisterOperatorRequest](/schemas/RegisterOperatorRequest.md). ```json { "name": "Default EU Manufacturing Operator", "regId": "EU-DEFAULT-001", "role": "MANUFACTURER" } ``` ## Responses - **201** — Operator registered (or an existing operator with the same regId was bound to your workspace). → [RegisterOperatorResponse](/schemas/RegisterOperatorResponse.md) - **400** — Two distinct bodies. → [OperatorMinimalErrorResponse](/schemas/OperatorMinimalErrorResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Database/handler failure. → [OperatorMinimalErrorResponse](/schemas/OperatorMinimalErrorResponse.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/operators' \ --data '{"name":"Default EU Manufacturing Operator","regId":"EU-DEFAULT-001","role":"MANUFACTURER"}' ``` ## See also Schemas: [OperatorMinimalErrorResponse](/schemas/OperatorMinimalErrorResponse.md), [RegisterOperatorRequest](/schemas/RegisterOperatorRequest.md), [RegisterOperatorResponse](/schemas/RegisterOperatorResponse.md). ================================================================================ # FILE: /okf/operations/getOperator.md ================================================================================ --- type: API Endpoint title: Fetch a single bound economic operator description: Fetches one economic operator by UUID, scoped to your workspace (404 if no operator with that id exists in your workspace). resource: https://opendpp-node.eu/api/v1/operators/{id} tags: - GET - economic-operators generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/operators/{id}` **Domain:** [Economic Operators](/tags/economic-operators.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Fetches one economic operator by UUID, scoped to your workspace (`404` if no operator with that id exists in your workspace). **Permission:** `operator:read`. An **operator-scoped API key** may only fetch its own operator (`403` otherwise). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Operator UUID (EconomicOperator.id). | ## Responses - **200** — The operator. → [OperatorGetResponse](/schemas/OperatorGetResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/operators/{id}' ``` ## See also Schemas: [OperatorGetResponse](/schemas/OperatorGetResponse.md). ================================================================================ # FILE: /okf/operations/updateOperator.md ================================================================================ --- type: API Endpoint title: Update an operator's name or role (regId is immutable) description: Edits an operator bound to your workspace. resource: https://opendpp-node.eu/api/v1/operators/{id} tags: - PATCH - economic-operators generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `PATCH /api/v1/operators/{id}` **Domain:** [Economic Operators](/tags/economic-operators.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Edits an operator bound to your workspace. Only `name` and `role` are editable; `regId` is the legal registry identifier and is **intentionally immutable** here (register the operator again under the correct id instead). Non-string or whitespace-only values are silently ignored; submitted values are trimmed. If no usable field is supplied (every field missing, non-string, or whitespace-only — including an empty object `{}` or an omitted body), the current operator row is returned unchanged with `200` and no audit event is written. The handler does not diff against current values: supplying a value identical to the current one still performs an update and writes an audit event. **Permission:** `operator:write`. Cookie-session clients must send `X-CSRF-Token`; Bearer clients are exempt. **Tenant-scoped:** operators are scoped to your workspace — `regId` is not globally unique. Registering a `regId` that another workspace also uses creates **your own** operator row; `name`/`role` edits never affect another workspace. When a change is applied, an `operator.updated` audit event is recorded. Unhandled database errors are normalized by the global error handler to the standard `{success: false, error, message}` envelope with a generic message (details are logged server-side). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Operator UUID (EconomicOperator.id). | ## Request body Schema: [UpdateOperatorRequest](/schemas/UpdateOperatorRequest.md). ```json { "name": "Default EU Manufacturing Operator B.V.", "role": "IMPORTER" } ``` ## Responses - **200** — The (possibly unchanged) operator row. → [UpdateOperatorResponse](/schemas/UpdateOperatorResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The operator does not exist or is not bound to your workspace. → [OperatorMinimalError](/schemas/OperatorMinimalError.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Server-side failure. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X PATCH 'https://opendpp-node.eu/api/v1/operators/{id}' \ --data '{"name":"Default EU Manufacturing Operator B.V.","role":"IMPORTER"}' ``` ## See also Schemas: [Error](/schemas/Error.md), [UpdateOperatorRequest](/schemas/UpdateOperatorRequest.md), [UpdateOperatorResponse](/schemas/UpdateOperatorResponse.md). ================================================================================ # FILE: /okf/operations/deleteOperator.md ================================================================================ --- type: API Endpoint title: Remove an operator (archives if it has passports, else hard-deletes) description: "Removes an operator, choosing automatically between two outcomes (ESPR passport-persistence compliance — an operator that still has passports must never be hard-deleted):" resource: https://opendpp-node.eu/api/v1/operators/{id} tags: - DELETE - economic-operators generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `DELETE /api/v1/operators/{id}` **Domain:** [Economic Operators](/tags/economic-operators.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Removes an operator, choosing automatically between two outcomes (ESPR passport-persistence compliance — an operator that still has passports must never be hard-deleted): - **Archive (soft delete)** — if the operator has one or more passports, it is archived instead of deleted: `archivedAt` is set on the operator and every active passport of the operator is archived with a `retentionUntil` deadline set to a platform-configured retention period from now (default 15 years). Archived passports remain **publicly resolvable** (the persistence duty) but are excluded from active management lists. Response: `{success: true, archived: true, archivedPassports: }`. Fully reversible via `POST /api/v1/operators/{id}/restore`. - **Hard delete** — if the operator has no passports it is permanently deleted (tenant bindings cascade-delete; user/facility/API-key references are set to null). Response: `{success: true, archived: false}` — no `archivedPassports` field. - **Fallback** — if the hard delete fails on a residual foreign-key reference, the operator is archived instead and the response is `{success: true, archived: true}` **without** `archivedPassports`. If even the fallback archive fails, `409` is returned. **Permission:** `operator:write`. Cookie-session clients must send `X-CSRF-Token`; Bearer clients are exempt. The operator must be bound to your workspace (`404` otherwise). **Tenant-scoped:** this affects only **your** workspace's operator and passports — operators are not shared across workspaces. Side effects: an `operator.archived` or `operator.deleted` audit event plus an in-app notification — on the primary archive and hard-delete paths only; the foreign-key fallback archive writes **no** audit event or notification. Unhandled database errors are normalized by the global error handler to the standard `{success: false, error, message}` envelope with a generic message (details are logged server-side). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Operator UUID (EconomicOperator.id). | ## Responses - **200** — Operator removed. → [DeleteOperatorResponse](/schemas/DeleteOperatorResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The operator does not exist or is not bound to your workspace. → [OperatorMinimalError](/schemas/OperatorMinimalError.md) - **409** — The operator could neither be hard-deleted nor archived (both attempts failed). → [OperatorMinimalError](/schemas/OperatorMinimalError.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Server-side failure. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X DELETE 'https://opendpp-node.eu/api/v1/operators/{id}' ``` ## See also Schemas: [DeleteOperatorResponse](/schemas/DeleteOperatorResponse.md), [Error](/schemas/Error.md), [OperatorMinimalError](/schemas/OperatorMinimalError.md). ================================================================================ # FILE: /okf/operations/restoreOperator.md ================================================================================ --- type: API Endpoint title: Restore an archived operator and its archived passports description: "Un-archives an operator that was soft-deleted by DELETE /api/v1/operators/{id} and brings its archived passports back into the active catalogue: clears the operator's archivedAt, then clears archivedAt and retentionUntil on every archived…" resource: https://opendpp-node.eu/api/v1/operators/{id}/restore tags: - POST - economic-operators generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/operators/{id}/restore` **Domain:** [Economic Operators](/tags/economic-operators.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Un-archives an operator that was soft-deleted by `DELETE /api/v1/operators/{id}` and brings its archived passports back into the active catalogue: clears the operator's `archivedAt`, then clears `archivedAt` and `retentionUntil` on every archived passport of the operator **except** passports that were independently `DECOMMISSIONED` (those keep their own retention clock and stay archived). Safe to call on a non-archived operator — it simply restores any archived passports the operator may have (`restoredPassports` may be `0`). No request body. **Permission:** `operator:write`. Cookie-session clients must send `X-CSRF-Token`; Bearer clients are exempt. `404` if the operator is not bound to your workspace. Side effects: an `operator.restored` audit event and an in-app notification. Unhandled database errors are normalized by the global error handler to the standard `{success: false, error, message}` envelope with a generic message (details are logged server-side). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Operator UUID (EconomicOperator.id). | ## Responses - **200** — Operator un-archived. → [RestoreOperatorResponse](/schemas/RestoreOperatorResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The operator does not exist or is not bound to your workspace. → [OperatorMinimalError](/schemas/OperatorMinimalError.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Server-side failure. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X POST 'https://opendpp-node.eu/api/v1/operators/{id}/restore' ``` ## See also Schemas: [Error](/schemas/Error.md), [RestoreOperatorResponse](/schemas/RestoreOperatorResponse.md). ================================================================================ # FILE: /okf/operations/rotateTenantKeys.md ================================================================================ --- type: API Endpoint title: Rotate the tenant's ECDSA signing key pair description: Generates a brand-new ECDSA prime256v1 (P-256) key pair for your workspace's advanced-seal signing and rotates it into the encrypted database vault, replacing the previous key. resource: https://opendpp-node.eu/api/v1/tenants/rotate-keys tags: - POST - eidas-keys generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/tenants/rotate-keys` **Domain:** [eIDAS Keys](/tags/eidas-keys.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Generates a brand-new ECDSA **prime256v1 (P-256)** key pair for your workspace's advanced-seal signing and rotates it into the encrypted database vault, replacing the previous key. No request body is required; a valid JSON body, if sent, is ignored. What happens: - The new private key (PKCS#8) is encrypted with AES-256-GCM (per-entry HKDF-derived key; the tenant id is bound as GCM additional authenticated data) and upserted into the vault — the **previous private key is overwritten and unrecoverable**. - The tenant's published `eidasPublicKey` is updated to the new public key (SPKI PEM), which is also returned in the response. - A best-effort X.509 identity certificate is minted from the platform seal CA, binding the new key to the tenant's legal name (creator identification); a certificate-minting failure does **not** fail the rotation (the certificate fields simply stay null until backfilled). **Operational impact:** rotation does not invalidate existing seals. Each sealed passport embeds the signing public key and certificate chain at sealing time, so previously sealed passports keep verifying with their embedded key material. Passports sealed after rotation use the new key. **Permission:** `key:write`. Cookie-session clients must send `X-CSRF-Token`; Bearer clients are exempt. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Responses - **200** — Key pair rotated. → [RotateTenantKeysResponse](/schemas/RotateTenantKeysResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Key generation, vault encryption, or database failure. → [OperatorMinimalErrorResponse](/schemas/OperatorMinimalErrorResponse.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X POST 'https://opendpp-node.eu/api/v1/tenants/rotate-keys' ``` ## See also Schemas: [OperatorMinimalErrorResponse](/schemas/OperatorMinimalErrorResponse.md), [RotateTenantKeysResponse](/schemas/RotateTenantKeysResponse.md). ================================================================================ # FILE: /okf/operations/listPassports.md ================================================================================ --- type: API Endpoint title: List passports in your workspace (paginated JSON-LD) description: Returns the non-archived passports of every economic operator bound to your workspace, newest first (createdAt DESC). resource: https://opendpp-node.eu/api/v1/passports tags: - GET - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/passports` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Returns the **non-archived** passports of every economic operator bound to your workspace, newest first (`createdAt DESC`). Operator-scoped API keys only see passports of their bound operator. **Permission:** `passport:read` (read-only — no subscription/402 gate). **Filtering:** `category` and `originCountry` are exact-match filters on the top-level `metadata` keys of the same name. Known `metadata.category` values: `textiles`, `batteries`, `electronics`, `cosmetics`, `toys`, `iron-steel`, `aluminium`, `chemicals`, `construction`; `originCountry` is ISO 3166-1 alpha-2. **Pagination:** `page` (default 1) and `limit` (default 10) are numeric strings matching `^[0-9]+$` — any other value is rejected with the framework's default 400 validation body (see 400). Parsed values are clamped server-side to `page >= 1` and `1 <= limit <= 100`. There is **no `total` count**; page until you receive fewer than `limit` items. **Serialization caveats:** - The redaction tier of each item depends on the credential's **role**: only `BRAND_OPERATOR` credentials receive the unredacted owner-tier document. Every other role — including `TENANT_ADMIN` — receives the public tier: `facilityDetails` (and, for `batteries`, `detailedPerformance` / `lifecycleAndInUse` / `circularityAndDisassembly`) are masked to the literal string `"[REDACTED - Privileged Access Required]"`. - `economicOperator.role` is **absent** from list items and `manufacturingFacility` is always `null` here — fetch a single passport (`GET /api/v1/passports/{id}`) for the facility node and operator role. - The response passes through a declared response schema: top-level keys other than `success`, `page`, `limit`, `passports` are stripped. Passport items allow additional properties, so undeclared item keys (`status`, `archivedAt`, `retentionUntil`, `manufacturingFacility`, the flattened metadata keys) pass through intact — but two **declared** item keys are mangled by their subschemas: the `@context` term-map object (second array element) is always emptied to `{}`, and `proof` is emptied to `{}` on sealed items (`null` on unsealed) — `signatureValue`, `merkleRoot`, `redactedLeaves`, `x5c` and `rfc3161` are all stripped from list output. Fetch a single passport (`GET /api/v1/passports/{id}`) or the public resolver for the verifiable proof block. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `` | | no | — | — | | `` | | no | — | — | | `category` | query | no | string | Exact-match filter on metadata.category. | | `originCountry` | query | no | string | Exact-match filter on metadata.originCountry (ISO 3166-1 alpha-2, e.g. PT). | ## Responses - **200** — Paginated list of JSON-LD passport documents. → [PassportListResponse](/schemas/PassportListResponse.md) - **400** — Route validation failure (framework default body — note statusCode/code keys, no success field): page or limit did not match ^[0-9]+$. - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/passports' ``` ## See also Schemas: [PassportListResponse](/schemas/PassportListResponse.md). ================================================================================ # FILE: /okf/operations/createPassport.md ================================================================================ --- type: API Endpoint title: Create (ingest) a Digital Product Passport description: Creates a SKU/type-level Digital Product Passport. resource: https://opendpp-node.eu/api/v1/passports tags: - POST - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/passports` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Creates a SKU/type-level Digital Product Passport. **Permission:** `passport:create` (Bearer `op_dpp_token_…` API key or session JWT; cookie sessions must also send the `X-CSRF-Token` double-submit header). Write operations are subject to subscription gating (**402**) and, where the workspace enforces it, MFA (**403**). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. **Body limit: 1 MiB (1,048,576 bytes)** → **413** beyond that. **Validation.** Unless `draft: true`, `metadata` is validated against the ESPR category rules for `metadata.category` plus cross-field rules (e.g. `materialComposition` percentages must sum to 100 ±0.1, `originCountry` must be a real ISO 3166-1 alpha-2 code). For five categories (textiles, batteries, electronics, chemicals, construction) the authoritative per-category JSON Schema is served live at `GET /api/v1/schemas/{category}`; the other four (cosmetics, toys, iron-steel, aluminium) are validated by built-in server-side rules and `GET /api/v1/schemas/{category}` returns **404** for them. Failure returns the **400 Validation Failed** body with per-field `errors[]` (plus `warnings[]` when any exist — the key is omitted entirely when there are none). A passing payload may still produce non-blocking `warnings[]`, echoed in the 201 — including a **privacy-by-design advisory** when the metadata *looks* like it carries personal data (a clearly-personal field name such as `email`/`firstName`, or an email-shaped value; scanned one level deep, at most one such advisory). A DPP should carry PRODUCT data, not PII (ESPR FAQ Q16); this advisory never blocks the save. `friendlyMessage` texts are localized via `?lang=` or `Accept-Language` (default `en`); category-validity errors (`metadata.category` missing or unknown) carry no `friendlyMessage`. **Drafts.** `draft: true` skips ALL validation, stores the passport with `status: "DRAFT"` (not publicly resolvable), returns `message: "Draft passport saved"` with `warnings: []`, and does **not** emit a webhook. **Identifier handling.** `productId` may be a GTIN-14 (14 digits, GS1 mod-10 check digit), a GRAI (14-digit numeric asset id + up to 16 alphanumeric serial chars), or a free-form SKU. A 14-digit `productId` whose GS1 mod-10 check digit is invalid is rejected with **400** (a typo'd GTIN is never silently downgraded to a SKU); a non-numeric or non-14-digit `productId` is accepted as a non-GS1 SKU and carries a non-blocking `warnings[]` advisory that it resolves via `/passport/{id}` with no scannable GS1 QR. A valid GTIN-14 is auto-copied into `metadata.gtin` (a GRAI into `metadata.grai`) before storage. The server mints a UUID passport id and a GS1 Digital Link URI `https://opendpp-node.eu/{01|8003}/{productId}`. **Operator binding.** With `operatorId` omitted, the passport is attributed to the first economic operator bound to your workspace; if no operator is bound at all the request fails **400** (the API never fabricates an operator identity — register one via `POST /api/v1/operators`). An `operatorId` not bound to your workspace → **403**. Operator-scoped API keys force their own operator and **403** on mismatch. The `(productId, operatorId)` pair is unique → **409** on duplicates. An optional `facilityId` must reference a Facility in your workspace (**400** otherwise). **Webhook:** non-draft creation transactionally enqueues a `passport.ingested` event whose payload is the public redacted JSON-LD passport document (same masking as the 201 `passport` field). Drafts emit nothing. **Response caveats:** the 201 `passport` field is the **public, redacted** JSON-LD representation — even for the creator. The owner-only metadata key `facilityDetails` is replaced with the literal placeholder `"[REDACTED - Privileged Access Required]"` (it appears as the placeholder even when you did not supply it), and for `category: "batteries"` the restricted legitimate-interest keys `detailedPerformance`, `lifecycleAndInUse` and `circularityAndDisassembly` (Battery Reg. Annex XIII parts 2-4) are masked the same way when present. `enrichment` is stored outside the validated metadata and Merkle seal and never appears in the JSON-LD document. The 201 body's top-level fields are `success`, `message`, `passport`, `warnings`, and the `vcReady`/`vcReadyReason` UNTP Verifiable-Credential readiness signal. **Other 400 bodies:** non-validation failures (whitespace-only `productId`, no bound operator, unknown `facilityId`) reuse status 400 with the plain `{"success": false, "error": "Bad Request", "message": …}` triple and **no** `errors`/`warnings` arrays. Requests rejected before the handler runs — request-body schema violations (e.g. missing `productId`) and malformed JSON — come back as just `{"error": "Bad Request", "message": …}`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `Idempotency-Key` | header | no | string | Optional client idempotency key (≤255 characters, no control characters). | | `lang` | query | no | string | Locale for localized friendlyMessage validation texts. | ## Request body Schema (required): [PassportCreateRequest](/schemas/PassportCreateRequest.md). ```json { "productId": "09501101530003", "operatorId": "5c1e0f3a-7b2d-4c8e-a91f-2d3e4f5a6b7c", "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 62.5 }, { "material": "Virgin steel", "percentage": 37.5 } ], "facilityDetails": [ { "facilityName": "Musterstahl Works Duisburg", "location": "Duisburg, DE", "activity": "Hot rolling" } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00417", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 62.5, "tensileStrengthClass": "S355", "carbonEmissionIntensityPerTon": 1.42 }, "enrichment": { "tagline": "Low-carbon structural steel", "images": [ { "url": "https://cdn.example.com/steel-beam.jpg", "caption": "S355 beam" } ] } } ``` ## Responses - **201** — Passport created (or draft saved). → [PassportIngestCreated](/schemas/PassportIngestCreated.md) - **400** — Three variants share this status: (1) Validation Failed — the metadata failed ESPR category / cross-field validation; carries per-field errors[] (and warnings[… → [PassportCreateBadRequest](/schemas/PassportCreateBadRequest.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **409** — A passport already exists for this (productId, operatorId) pair. → [Error](/schemas/Error.md) - **413** — Body exceeds the 1 MiB (1,048,576-byte) body limit. - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/passports' \ --data '{"productId":"09501101530003","operatorId":"5c1e0f3a-7b2d-4c8e-a91f-2d3e4f5a6b7c","metadata":{"category":"iron-steel","originCountry":"DE","materialComposition":[{"material":"Recycled steel","percentage":62.5},{"material":"Virgin steel","percentage":37.5}],"facilityDetails":[{"facilityName":"Musterstahl Works Duisburg","location":"Duisburg, DE","activity":"Hot rolling"}],"regulatoryCompliance":{"ceMarking":true,"certificates":[{"name":"EN 10025-2 Mill Certificate","referenceNumber":"MC-2026-00417","issuer":"TUV Rheinland"}]},"scrapMetalContentRatio":62.5,"tensileStrengthClass":"S355","carbonEm…' ``` ## See also Schemas: [Error](/schemas/Error.md), [PassportCreateBadRequest](/schemas/PassportCreateBadRequest.md), [PassportCreateRequest](/schemas/PassportCreateRequest.md), [PassportIngestCreated](/schemas/PassportIngestCreated.md). ================================================================================ # FILE: /okf/operations/validatePassport.md ================================================================================ --- type: API Endpoint title: Dry-run ESPR validation of passport metadata (nothing is stored) description: Runs the full ESPR category schema validation on a metadata payload without persisting anything — intended for pre-flight checks in integration pipelines. resource: https://opendpp-node.eu/api/v1/passports/validate-only tags: - POST - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/passports/validate-only` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Runs the full ESPR category schema validation on a metadata payload **without persisting anything** — intended for pre-flight checks in integration pipelines. **Permission:** `passport:create` (Bearer API key or session JWT + CSRF for cookie sessions). Despite being read-only in effect, it is gated as a write permission, so subscription gating (**402**) applies. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. **Body limit: 262,144 bytes (256 KiB)** → **413** beyond that. **Behavioral caveats:** - `operatorId` is accepted by the body schema but **ignored** by the handler. - The 200 body always carries `errors: []`; `warnings` is **omitted entirely** when there are none (it is not an empty array). The same omission applies to `warnings` on the 400 Validation Failed body. - `friendlyMessage` localization via `?lang=` / `Accept-Language` (28 languages, default `en`); category-validity errors (`metadata.category` missing or unknown) carry no `friendlyMessage`. - Structural rejections of the request body (e.g. missing `productId`, non-object `metadata`) and malformed JSON return just `{"error": "Bad Request", "message": …}`; the structurally bad inputs that reach the handler are a whitespace-only `productId` and a malformed GTIN-14 `productId` (14 digits failing the GS1 mod-10 check), each answered with the fuller `Bad Request` body shown below. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `lang` | query | no | string | Locale for localized friendlyMessage validation texts (en, bg, hr, cs, da, nl, et, fi, fr, de, el, hu, ga, it, lv, lt, mt, pl, pt, ro, sk, sl, es, sv, no, is,… | ## Request body Schema (required): [PassportValidateOnlyRequest](/schemas/PassportValidateOnlyRequest.md). ```json { "productId": "09501101530003", "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 62.5 }, { "material": "Virgin steel", "percentage": 37.5 } ], "facilityDetails": [ { "facilityName": "Musterstahl Works Duisburg", "location": "Duisburg, DE", "activity": "Hot rolling" } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00417", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 62.5, "tensileStrengthClass": "S355", "carbonEmissionIntensityPerTon": 1.42 } } ``` ## Responses - **200** — Metadata is valid for its ESPR category. → [PassportValidateOnlyResult](/schemas/PassportValidateOnlyResult.md) - **400** — Validation failed, or the request body was structurally invalid. → [PassportValidateOnlyError](/schemas/PassportValidateOnlyError.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **413** — Body exceeds the 262,144-byte (256 KiB) route body limit. - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/passports/validate-only' \ --data '{"productId":"09501101530003","metadata":{"category":"iron-steel","originCountry":"DE","materialComposition":[{"material":"Recycled steel","percentage":62.5},{"material":"Virgin steel","percentage":37.5}],"facilityDetails":[{"facilityName":"Musterstahl Works Duisburg","location":"Duisburg, DE","activity":"Hot rolling"}],"regulatoryCompliance":{"ceMarking":true,"certificates":[{"name":"EN 10025-2 Mill Certificate","referenceNumber":"MC-2026-00417","issuer":"TUV Rheinland"}]},"scrapMetalContentRatio":62.5,"tensileStrengthClass":"S355","carbonEmissionIntensityPerTon":1.42}}' ``` ## See also Schemas: [PassportValidateOnlyError](/schemas/PassportValidateOnlyError.md), [PassportValidateOnlyRequest](/schemas/PassportValidateOnlyRequest.md), [PassportValidateOnlyResult](/schemas/PassportValidateOnlyResult.md). ================================================================================ # FILE: /okf/operations/validatePassportPublic.md ================================================================================ --- type: API Endpoint title: Permission-free dry-run ESPR metadata validation (strictly rate-limited) description: Identical validation semantics to POST /api/v1/passports/validate-only, but requires no specific permission — any valid API key or Console session is accepted, so every plan including the free tier can call it. resource: https://opendpp-node.eu/api/v1/passports/validate-only-public tags: - POST - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/passports/validate-only-public` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Identical validation semantics to `POST /api/v1/passports/validate-only`, but requires **no specific permission** — any valid API key or Console session is accepted, so every plan including the free tier can call it. Nothing is persisted. **Authentication is required.** Until contract 1.12.0 this endpoint was reachable anonymously; it is not any more, because it runs the full validation engine and was usable as free unauthenticated compute. An anonymous call now returns **401**. The path keeps its `-public` segment for continuity — "public" here means *no permission and no tenant scope*, not *unauthenticated*. **Rate limit: 10 requests/min per IP** — a strict per-route limit that **replaces** the global ceiling for this endpoint (emits `x-ratelimit-limit` / `x-ratelimit-remaining` / `x-ratelimit-reset` headers and `retry-after` on 429). **Body limit: 65,536 bytes (64 KiB)** → **413** beyond that. Both caps remain as defence in depth against authenticated abuse. The credential is checked **before the body is parsed**, so an anonymous oversized body is rejected as **401**, not 413. **Behavioral caveats:** - No tenant context: `operatorId` is accepted but ignored. - The 200 body always carries `errors: []`; `warnings` is omitted entirely when there are none (same omission on the 400 Validation Failed body). - Error/warning `friendlyMessage` localization via `?lang=` / `Accept-Language` (28 languages, default `en`); category-validity errors carry no `friendlyMessage`. - Structural rejections of the request body (e.g. missing `productId`) and malformed JSON return just `{"error": "Bad Request", "message": …}`; a whitespace-only `productId` or a malformed GTIN-14 `productId` (14 digits failing the GS1 mod-10 check) gets the fuller `Bad Request` body shown below. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `lang` | query | no | string | Locale for localized friendlyMessage validation texts (en, bg, hr, cs, da, nl, et, fi, fr, de, el, hu, ga, it, lv, lt, mt, pl, pt, ro, sk, sl, es, sv, no, is,… | ## Request body Schema (required): [PassportValidateOnlyRequest](/schemas/PassportValidateOnlyRequest.md). ```json { "productId": "09501101530003", "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 62.5 }, { "material": "Virgin steel", "percentage": 37.5 } ], "facilityDetails": [ { "facilityName": "Musterstahl Works Duisburg", "location": "Duisburg, DE", "activity": "Hot rolling" } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00417", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 62.5, "tensileStrengthClass": "S355", "carbonEmissionIntensityPerTon": 1.42 } } ``` ## Responses - **200** — Metadata is valid for its ESPR category. → [PassportValidateOnlyResult](/schemas/PassportValidateOnlyResult.md) - **400** — Validation failed or the body was structurally invalid — same three variants as the authenticated validate-only endpoint. → [PassportValidateOnlyError](/schemas/PassportValidateOnlyError.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **413** — Body exceeds the 65,536-byte (64 KiB) route body limit. - **429** — Rate limit exceeded. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/passports/validate-only-public' \ --data '{"productId":"09501101530003","metadata":{"category":"iron-steel","originCountry":"DE","materialComposition":[{"material":"Recycled steel","percentage":62.5},{"material":"Virgin steel","percentage":37.5}],"facilityDetails":[{"facilityName":"Musterstahl Works Duisburg","location":"Duisburg, DE","activity":"Hot rolling"}],"regulatoryCompliance":{"ceMarking":true,"certificates":[{"name":"EN 10025-2 Mill Certificate","referenceNumber":"MC-2026-00417","issuer":"TUV Rheinland"}]},"scrapMetalContentRatio":62.5,"tensileStrengthClass":"S355","carbonEmissionIntensityPerTon":1.42}}' ``` ## See also Schemas: [PassportValidateOnlyError](/schemas/PassportValidateOnlyError.md), [PassportValidateOnlyRequest](/schemas/PassportValidateOnlyRequest.md), [PassportValidateOnlyResult](/schemas/PassportValidateOnlyResult.md). ================================================================================ # FILE: /okf/operations/bulkIngestPassports.md ================================================================================ --- type: API Endpoint title: Bulk-ingest up to 200 passports with per-row error reporting description: "Ingests up to 200 passports in one request with partial-success semantics: each row is validated and inserted independently; failed rows are skipped and reported as human-readable strings in errors[]." resource: https://opendpp-node.eu/api/v1/passports/bulk tags: - POST - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/passports/bulk` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Ingests up to **200** passports in one request with **partial-success semantics**: each row is validated and inserted independently; failed rows are skipped and reported as human-readable strings in `errors[]`. Returns **201** as long as at least one row was inserted (even with row errors); returns **400 Bulk Ingestion Failed** only when **every** row failed. **Permission:** `passport:create` (Bearer API key or session JWT + CSRF for cookie sessions; subscription gating → **402**). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. **Body limit: 1 MiB (1,048,576 bytes)** → **413** beyond that; in practice the `maxItems: 200` envelope cap is the effective bound for typical rows. Envelope violations — empty array, more than 200 items, missing `passports` — are rejected before any row is processed, with the full default validation error body (`{statusCode, code, error, message}`). **Per-row behavior (differences from `POST /api/v1/passports`):** - No `draft` support: every inserted row is created with `status: "ACTIVE"`. No `enrichment` support. - A valid GTIN-14/GRAI `productId` is **not** auto-copied into `metadata.gtin`/`metadata.grai` (unlike single ingestion). - Operator resolution per row: explicit `operatorId` must be bound to your workspace; otherwise the workspace's first bound operator is used; operator-scoped API keys force their operator. Lookups are cached within the request. - Duplicate `(productId, operatorId)` rows, unknown facilities, and per-row DB failures become `errors[]` strings (prefixed `[SKU: ]`), never a request-level failure. - Each successfully inserted row **transactionally enqueues a `passport.ingested` webhook event** (public redacted JSON-LD payload). - Row validation messages use the localized `friendlyMessage` where the engine provides one (`?lang=` / `Accept-Language`); category-validity errors fall back to the technical `path: message` form. Note the 400 `Bulk Ingestion Failed` body has **no `message` field**, and `errors` is an array of **strings** (not objects). ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `Idempotency-Key` | header | no | string | Optional client idempotency key (≤255 characters, no control characters). | | `lang` | query | no | string | Locale for the localized validation text inside per-row errors[] strings (en, bg, hr, cs, da, nl, et, fi, fr, de, el, hu, ga, it, lv, lt, mt, pl, pt, ro, sk, s… | ## Request body Schema (required): [PassportBulkRequest](/schemas/PassportBulkRequest.md). ```json { "passports": [ { "productId": "09501101530003", "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 62.5 }, { "material": "Virgin steel", "percentage": 37.5 } ], "facilityDetails": [ { "facilityName": "Musterstahl Works Duisburg", "location": "Duisburg, DE", "activity": "Hot rolling" } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00417", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 62.5, "tensileStrengthClass": "S355", "carbonEmissionIntensityPerTon": 1.42 } }, { "productId": "09501101530010", "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 100 } ], "facilityDetails": [ { "facilityName": "Musterstahl Works Duisburg", "location": "Duisburg, DE", "activity": "Cold rolling" } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00418", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 100, "tensileStrengthClass": "S275", "carbonEmissionIntensityPerTon": 0.61 } } ] } ``` ## Responses - **201** — Bulk run finished with at least one inserted row. → [PassportBulkResult](/schemas/PassportBulkResult.md) - **400** — Either every row failed (Bulk Ingestion Failed, with string errors[] and no message field), or the request never reached row processing: envelope violations of… → [PassportBulkBadRequest](/schemas/PassportBulkBadRequest.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **413** — Body exceeds the 1 MiB (1,048,576-byte) body limit. - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/passports/bulk' \ --data '{"passports":[{"productId":"09501101530003","metadata":{"category":"iron-steel","originCountry":"DE","materialComposition":[{"material":"Recycled steel","percentage":62.5},{"material":"Virgin steel","percentage":37.5}],"facilityDetails":[{"facilityName":"Musterstahl Works Duisburg","location":"Duisburg, DE","activity":"Hot rolling"}],"regulatoryCompliance":{"ceMarking":true,"certificates":[{"name":"EN 10025-2 Mill Certificate","referenceNumber":"MC-2026-00417","issuer":"TUV Rheinland"}]},"scrapMetalContentRatio":62.5,"tensileStrengthClass":"S355","carbonEmissionIntensityPerTon":1.42}},{"produc…' ``` ## See also Schemas: [PassportBulkBadRequest](/schemas/PassportBulkBadRequest.md), [PassportBulkRequest](/schemas/PassportBulkRequest.md), [PassportBulkResult](/schemas/PassportBulkResult.md). ================================================================================ # FILE: /okf/operations/ingestPassportFromAas.md ================================================================================ --- type: API Endpoint title: Ingest a passport from an AAS JSON Environment (seal-verified) description: Ingests (creates or updates) a Digital Product Passport from an Industry-4.0 Asset Administration Shell (AAS) JSON Environment — the same format produced by OpenDPP's own AAS export. resource: https://opendpp-node.eu/api/v1/passports/aas/ingest tags: - POST - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/passports/aas/ingest` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Ingests (creates **or updates**) a Digital Product Passport from an Industry-4.0 **Asset Administration Shell (AAS) JSON Environment** — the same format produced by OpenDPP's own AAS export. **Permission:** `passport:create` (Bearer API key or session JWT + CSRF for cookie sessions; subscription gating → **402**). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. **Body limit: 262,144 bytes (256 KiB)** → **413**. **Parsing.** The environment must contain a `submodels` array including a submodel with `idShort: "ComplianceMetadata"`, whose `submodelElements` are parsed back into the metadata object; missing it fails 400 (`Ingestion Failed`). `productId` is resolved from `metadata.gtin` || `metadata.grai` || `metadata.productId` || the first shell's `assetInformation.specificAssetIds` entry named `productId` — unresolvable → 400 `Bad Request`. The parsed metadata then passes the full ESPR category validation (400 `Validation Failed` with `errors[]`). **seal verification.** If the environment embeds an `eidasVerificationSeal` submodel (`digitalSealHash` / `cryptographicSignature` / `pemPublicKey` elements), the seal is verified against **your tenant's server-held signing public key** — never the key embedded in the request (self-signing is rejected by design). An embedded seal that fails verification → **400 `Signature Verification Failed`**; this includes the case where your workspace holds no matching key. `isSealed`/`signatureVerified` in the 201 echo the outcome (both `false` for unsealed documents). **Upsert semantics.** If a passport already exists for the resolved `(productId, operator)` pair: a **sealed** existing passport refuses re-ingestion (**403** — re-seal explicitly after changes); an unsealed one has its metadata, Merkle tree and seal fields **replaced**, still answering **201**. Operator resolution: operator-scoped API keys use their own operator and **403** when that operator is not bound to your workspace; otherwise the workspace's first bound operator is used; none bound → 400. **Caveats:** - **NO webhook is emitted** — unlike `POST /api/v1/passports` and `/bulk`, AAS ingestion never enqueues `passport.ingested` (or any other event). - The catch-all error path returns **400 `Ingestion Failed`** with the underlying parse/processing message — even for internal failures (this handler does not emit its own 500). - Validation `friendlyMessage` localization via `?lang=` / `Accept-Language`; category-validity errors carry no `friendlyMessage`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `lang` | query | no | string | Locale for localized friendlyMessage validation texts (en, bg, hr, cs, da, nl, et, fi, fr, de, el, hu, ga, it, lv, lt, mt, pl, pt, ro, sk, sl, es, sv, no, is,… | ## Request body Schema (required): [AasEnvironmentInput](/schemas/AasEnvironmentInput.md). ## Responses - **201** — Passport created or (if it existed unsealed) updated from the AAS environment. → [AasIngestCreated](/schemas/AasIngestCreated.md) - **400** — Four variants share this status: Bad Request (non-object body, unresolvable productId, no bound operator), Signature Verification Failed (embedded seal invalid… → [AasIngestBadRequest](/schemas/AasIngestBadRequest.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **413** — Body exceeds the 262,144-byte (256 KiB) route body limit. - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X POST 'https://opendpp-node.eu/api/v1/passports/aas/ingest' ``` ## See also Schemas: [AasEnvironmentInput](/schemas/AasEnvironmentInput.md), [AasIngestBadRequest](/schemas/AasIngestBadRequest.md), [AasIngestCreated](/schemas/AasIngestCreated.md). ================================================================================ # FILE: /okf/operations/passportVcReadinessReport.md ================================================================================ --- type: API Endpoint title: Catalog-wide UNTP Verifiable-Credential readiness report description: A read-only, tenant-scoped report of which SKUs in your catalog can / can't emit a UNTP Verifiable Credential, and why — so you can fix a whole catalog before relying on VCs, instead of probing passports one at a time. resource: https://opendpp-node.eu/api/v1/passports/vc-readiness tags: - GET - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/passports/vc-readiness` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. A read-only, tenant-scoped report of which SKUs in your catalog can / can't emit a UNTP **Verifiable Credential**, and why — so you can fix a whole catalog before relying on VCs, instead of probing passports one at a time. It **aggregates the same per-passport `vcReady` signal** returned on every ingest response: a passport is VC-ready only when it links a manufacturing `Facility` with a country of production. **Permission:** `passport:read` (read-only — no subscription/402 gate). Operator scoping + the non-archived filter match the passports list. **Shape:** each `results[]` row is `{ id, productId, vcReady, blockers[] }` — `blockers[]` reuses the SAME actionable reason the single-passport signal exposes (empty when ready). The top-level `ready` / `notReady` rollup is **catalog-wide** (counts every non-archived passport), while `results` is **paginated** — `page` (default 1) + `limit` (default 100, max 200), with `total` / `totalPages`. NOTE: because the rollup is catalog-wide but `results` is one page, `ready` is generally NOT the count of `vcReady:true` rows on the current page — page through all `totalPages` to enumerate every SKU. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `` | | no | — | — | | `` | | no | — | — | ## Responses - **200** — The paginated VC-readiness report with a catalog-wide ready/notReady rollup. ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/passports/vc-readiness' ``` ================================================================================ # FILE: /okf/operations/getPassport.md ================================================================================ --- type: API Endpoint title: Fetch a single passport (content-negotiated JSON-LD / AAS / HTML) description: Owner-side alias of the public resolver. resource: https://opendpp-node.eu/api/v1/passports/{id} tags: - GET - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/passports/{id}` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Owner-side alias of the public resolver. Accepts either the passport **UUID** or its caller-supplied **`productId`** (GTIN-14 / GRAI / SKU), scoped to operators bound to your workspace. After the scoped lookup the request is **re-dispatched internally to `GET /passport/{uuid}`**, forwarding all request headers, and the inner response (status, content type, body) is returned as-is. **Permission:** `passport:read` (read-only — no subscription/402 gate). **Content negotiation** (substring match on `Accept`): `application/aas+json` → role-filtered AAS environment; `application/vc+jwt` → enveloping UNTP Verifiable Credential; `application/vc+ld+json` → the same credential with an embedded `ecdsa-jcs-2019` W3C Data Integrity proof; `application/dc+sd-jwt` (legacy `vc+sd-jwt` accepted) → SD-JWT-VC selective disclosure (these three return `406 Not Acceptable` when the passport has no manufacturing facility with a country of production); `text/html` → SSR passport page; anything else (including `application/json`, `*/*`, or no header) → JSON-LD with `Content-Type: application/ld+json` (the default). The VC and SD-JWT representations are forwarded verbatim from `GET /passport/{id}` — see that operation for the full credential semantics. **Access-tier caveat (privilege is resolved from the *forwarded* headers, not the already-authenticated context):** only **database API keys** (`Authorization: Bearer op_dpp_token_…`) of the owning or operator-bound tenant are recognized as owner by the inner resolver. Those callers get the **owner-tier** document: `facilityDetails` and battery restricted keys unmasked, `manufacturingFacility` includes `streetAddress`/`city`/`postalCode`, and DRAFT passports are visible. Callers authenticated with a **JWT session** (login cookie or bearer JWT) receive the **public-redacted** tier instead, and DRAFT passports answer 404 with the forwarded public body (no `success` field). Every successful resolution records an anonymized-IP access audit entry. **Rate limits:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys, under a per-IP ceiling; `x-ratelimit-*` headers and a `Retry-After` on **429**. **Plus** the forwarded public resolver's own limiter (30 req/min/IP, no headers) — both 429 shapes are possible (see 429). ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Passport UUID or caller-supplied productId (GTIN-14 / GRAI / SKU). | ## Responses - **200** — The resolved passport. → [PassportAasEnvironment](/schemas/PassportAasEnvironment.md), [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — Two distinct bodies. → [PassportGetNotFound](/schemas/PassportGetNotFound.md) - **406** — The requested representation cannot be produced for this resource. → [Error](/schemas/Error.md) - **429** — Two possible sources. → [PassportGetTooManyRequests](/schemas/PassportGetTooManyRequests.md) - **500** — Unexpected failure. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/passports/{id}' ``` ## See also Schemas: [Error](/schemas/Error.md), [PassportAasEnvironment](/schemas/PassportAasEnvironment.md), [PassportGetNotFound](/schemas/PassportGetNotFound.md), [PassportGetTooManyRequests](/schemas/PassportGetTooManyRequests.md), [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md). ================================================================================ # FILE: /okf/operations/updatePassport.md ================================================================================ --- type: API Endpoint title: Update passport metadata (versioned to history) description: Replaces the passport's metadata (the Merkle root and leaf hashes are recomputed) and snapshots the previous metadata into the passport's version history (version = count + 1, changedBy = user email or api-key:, changeReason defaults t… resource: https://opendpp-node.eu/api/v1/passports/{id} tags: - PUT - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `PUT /api/v1/passports/{id}` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Replaces the passport's `metadata` (the Merkle root and leaf hashes are recomputed) and snapshots the **previous** metadata into the passport's version history (version = count + 1, `changedBy` = user email or `api-key:`, `changeReason` defaults to `"API Update"`). **Permission:** `passport:update` (write — subscription gating applies, see 402). Cookie sessions must send `X-CSRF-Token` (double-submit); Bearer/API-key clients are exempt. **Lookup:** by passport **UUID only** — `productId` aliasing is NOT supported on this endpoint. The passport must belong to an operator bound to your workspace. **Draft semantics (`draft` flag):** - `draft: true` **skips ESPR validation entirely** and forces `status: "DRAFT"` — note this also demotes an already-published (ACTIVE/RECALLED/DECOMMISSIONED) passport back to DRAFT. - `draft` absent/false: `metadata` is validated against the ESPR category rules (400 on failure — see below). If the passport was a DRAFT it is **published**: status becomes `ACTIVE`, a `passport.ingested` webhook is enqueued transactionally (public-redacted JSON-LD payload) and an in-app notification is created best-effort afterwards. Editing an already-published (live) passport leaves its status untouched and enqueues a `passport.updated` webhook instead (same public-redacted JSON-LD payload). **Validation divergence:** the 400 validation body here contains `errors` but — unlike `POST /api/v1/passports` — **never a `warnings` array**. `friendlyMessage` is localized via the `lang` query parameter or `Accept-Language` (28 languages, default `en`; unsupported values silently fall back). **Sealed passports are immutable in place:** if `digitalSeal` is set the update is refused with **403** (message: "This passport is sealed and cannot be edited in place — editing would invalidate the eIDAS advanced electronic seal. Re-seal explicitly after any change."). **Facility:** omit `facilityId` to leave it unchanged; pass `null` or `""` to detach; pass a facility UUID owned by your tenant to attach (400 if not found in your workspace). **Enrichment:** include the `enrichment` key (even as `null`/`{}`) to overwrite the presentational marketing block; omit it to leave it unchanged. Values are sanitized server-side (truncated/sliced, http(s) URLs only), never rejected. **Response caveat:** the returned `passport` document is serialized at the **public** redaction tier — `facilityDetails` (and battery restricted keys) appear as `"[REDACTED - Privileged Access Required]"` even though you are the owner. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Passport UUID. | | `lang` | query | no | string | Locale for friendlyMessage localization in validation errors. | ## Request body Schema (required): [PassportUpdateRequest](/schemas/PassportUpdateRequest.md). ```json { "metadata": { "category": "textiles", "originCountry": "PT", "materialComposition": [ { "material": "Organic cotton", "percentage": 80 }, { "material": "Recycled polyester", "percentage": 20 } ], "fiberComposition": [ { "fiber": "cotton", "percentage": 80 }, { "fiber": "polyester", "percentage": 20 } ], "careInstructions": "Machine wash cold, line dry", "size": "M", "facilityDetails": [ { "facilityName": "Aurora Spinning Mill", "location": "Porto, PT", "activity": "Spinning", "eudrPlots": [ { "plotId": "PLOT-001", "polygonType": "point", "coordinates": [ { "lat": 41.1579, "lng": -8.6291 } ] } ], "traceabilityDocs": [ { "documentName": "GOTS scope certificate", "documentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "documentUrl": "https://docs.aurora-textiles.example/gots.pdf" } ] } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "GOTS", "referenceNumber": "GOTS-2026-0042", "issuer": "Control Union", "validUntil": "2027-05-31" } ] } }, "changeReason": "Updated fiber composition after supplier audit", "facilityId": "5b21cf12-7d24-4a8e-9a3c-2f1f4f4f9d10" } ``` ## Responses - **200** — Updated (or published) passport. → [PassportUpdateResponse](/schemas/PassportUpdateResponse.md) - **400** — Either a plain Bad Request — body is not a JSON object; metadata missing/not an object; facilityId not found in your workspace (Facility not found… → [PassportUpdateBadRequest](/schemas/PassportUpdateBadRequest.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — History snapshot or transactional update failure returns the standard envelope with the message "Failed to update passport". → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X PUT 'https://opendpp-node.eu/api/v1/passports/{id}' \ --data '{"metadata":{"category":"textiles","originCountry":"PT","materialComposition":[{"material":"Organic cotton","percentage":80},{"material":"Recycled polyester","percentage":20}],"fiberComposition":[{"fiber":"cotton","percentage":80},{"fiber":"polyester","percentage":20}],"careInstructions":"Machine wash cold, line dry","size":"M","facilityDetails":[{"facilityName":"Aurora Spinning Mill","location":"Porto, PT","activity":"Spinning","eudrPlots":[{"plotId":"PLOT-001","polygonType":"point","coordinates":[{"lat":41.1579,"lng":-8.6291}]}],"traceabilityDocs":[{"documentName":"GOTS scope certificate","d…' ``` ## See also Schemas: [Error](/schemas/Error.md), [PassportUpdateBadRequest](/schemas/PassportUpdateBadRequest.md), [PassportUpdateRequest](/schemas/PassportUpdateRequest.md), [PassportUpdateResponse](/schemas/PassportUpdateResponse.md). ================================================================================ # FILE: /okf/operations/deleteDraftPassport.md ================================================================================ --- type: API Endpoint title: Permanently delete a DRAFT passport description: Hard-deletes a passport only while it is a DRAFT (never published, not publicly resolvable, no retention duty). resource: https://opendpp-node.eu/api/v1/passports/{id} tags: - DELETE - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `DELETE /api/v1/passports/{id}` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Hard-deletes a passport **only while it is a DRAFT** (never published, not publicly resolvable, no retention duty). Children (history, access logs, battery units) cascade on delete. Published passports (ACTIVE/RECALLED/DECOMMISSIONED) are refused with **409** — they must be decommissioned/archived through the status lifecycle (`PUT /api/v1/passports/{id}/status`) to satisfy the ESPR persistence duty. **Permission:** `passport:update` (write — subscription gating applies, see 402). Cookie sessions must send `X-CSRF-Token`; Bearer/API-key clients are exempt. **Lookup:** by passport **UUID only** (no `productId` aliasing) and only within the passport's **owning tenant** — an operator-binding alone is not sufficient, unlike PUT. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Passport UUID. | ## Responses - **200** — Draft deleted. - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **409** — The passport is not a DRAFT — published passports cannot be hard-deleted. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected failure. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X DELETE 'https://opendpp-node.eu/api/v1/passports/{id}' ``` ## See also Schemas: [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/sealPassport.md ================================================================================ --- type: API Endpoint title: Apply the tenant's advanced electronic seal description: Signs the passport's Merkle root (SHA-256 tree over the key-sorted top-level metadata entries) with the tenant's vault-held ECDSA P-256 (prime256v1) private key, producing an advanced electronic seal (this is a local cryptographic seal — N… resource: https://opendpp-node.eu/api/v1/passports/{id}/seal tags: - POST - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/passports/{id}/seal` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Signs the passport's Merkle root (SHA-256 tree over the key-sorted top-level `metadata` entries) with the tenant's vault-held **ECDSA P-256 (prime256v1)** private key, producing an **advanced** electronic seal (this is a local cryptographic seal — NOT a Commission/EU-registry registration, and NOT a qualified seal). The base64 signature is stored as `digitalSeal` together with the signing public key (PEM), the X.509 chain binding the key to the tenant's legal identity (surfaced as `proof.x5c`, leaf first, base64 DER), and — **best-effort, opt-in** — an RFC 3161 trusted timestamp over SHA-256(merkleRoot) (`proof.rfc3161`; a TSA outage or missing configuration never blocks sealing, the field is simply absent). A `passport.sealed` webhook is enqueued transactionally with the update (payload: the public-redacted JSON-LD document including the full `proof` block). **Permission:** `passport:seal` (write — subscription gating applies, see 402). Cookie sessions must send `X-CSRF-Token`; Bearer/API-key clients are exempt. **Lookup:** passport **UUID or `productId`** (UUID tried first), restricted to the passport's **owning tenant**. **Behavioral caveats:** - The route does **not** modify the passport's `status` — despite the success message's "and published" wording, a DRAFT stays a DRAFT after sealing. Publish via `PUT /api/v1/passports/{id}` (validated save) instead. - Re-sealing an already-sealed passport is allowed and **overwrites** the previous seal/timestamp. - Once sealed, in-place metadata edits are refused (403 on `PUT /api/v1/passports/{id}`). - Requires the tenant's signing key pair to exist — otherwise 400. - The returned `passport` document is serialized at the **public** redaction tier (masked keys keep their true leaf hashes in `proof.redactedLeaves`, so the seal stays offline-verifiable after redaction). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Passport UUID or caller-supplied productId (GTIN-14 / GRAI / SKU). | ## Responses - **200** — Passport sealed. → [PassportSealResponse](/schemas/PassportSealResponse.md) - **400** — Missing identifier, or the tenant has no signing key pair configured. → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X POST 'https://opendpp-node.eu/api/v1/passports/{id}/seal' ``` ## See also Schemas: [Error](/schemas/Error.md), [PassportSealResponse](/schemas/PassportSealResponse.md). ================================================================================ # FILE: /okf/operations/updatePassportStatus.md ================================================================================ --- type: API Endpoint title: Transition passport lifecycle status (recall / decommission / reactivate) description: Transitions a published passport between live lifecycle states. resource: https://opendpp-node.eu/api/v1/passports/{id}/status tags: - PUT - passports generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `PUT /api/v1/passports/{id}/status` **Domain:** [Passports](/tags/passports.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Transitions a **published** passport between live lifecycle states. The request body carries only `status` (any other keys are ignored — there is no `reason` field; the history entry's change reason is auto-generated as `Status changed: → `). **Permission:** `passport:update` (write — subscription gating applies, see 402). Cookie sessions must send `X-CSRF-Token`; Bearer/API-key clients are exempt. **Lookup:** passport **UUID or `productId`** (UUID tried first), scoped to operators bound to your workspace. **Effects:** - `DECOMMISSIONED` — sets `retentionUntil = now + the configured retention period` (default 15 years), starting the minimum-availability retention clock. The passport stays publicly resolvable. - `ACTIVE` (reactivation) — clears `retentionUntil` **and** `archivedAt`. - `RECALLED` — marks the product recalled. - The status change, the version-history entry (who/when/what) and the webhook enqueue are **transactional**; an in-app notification is created **best-effort after the transaction commits** (a notification failure never affects the response). **Webhooks:** `RECALLED` enqueues `passport.recalled`; any other transition (`DECOMMISSIONED`, reactivate-to-`ACTIVE`) enqueues `passport.status_updated` — note that `passport.status_updated` is **not** an explicitly subscribable event filter, so only wildcard (`"*"`) webhook subscriptions receive it. Payloads are the public-redacted JSON-LD document. **Caveats:** DRAFT passports are refused with 409 (publish first via a validated `PUT /api/v1/passports/{id}`). Sealed passports CAN change status — `status` is stored alongside the document, not inside the sealed metadata Merkle tree. The returned `passport` document is serialized at the **public** redaction tier. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Passport UUID or caller-supplied productId (GTIN-14 / GRAI / SKU). | ## Request body Schema (required): [PassportStatusUpdateRequest](/schemas/PassportStatusUpdateRequest.md). ```json { "status": "DECOMMISSIONED" } ``` ## Responses - **200** — Status updated. → [PassportStatusUpdateResponse](/schemas/PassportStatusUpdateResponse.md) - **400** — status missing or not one of the allowed values. → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **409** — The passport is a DRAFT — drafts cannot transition to a live status here. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X PUT 'https://opendpp-node.eu/api/v1/passports/{id}/status' \ --data '{"status":"DECOMMISSIONED"}' ``` ## See also Schemas: [Error](/schemas/Error.md), [PassportStatusUpdateRequest](/schemas/PassportStatusUpdateRequest.md), [PassportStatusUpdateResponse](/schemas/PassportStatusUpdateResponse.md). ================================================================================ # FILE: /okf/operations/resolvePublicPassport.md ================================================================================ --- type: API Endpoint title: Resolve a passport by UUID (JSON-LD / AAS / HTML) description: Public, content-negotiated resolution of a Digital Product Passport by its server-assigned UUID. resource: https://opendpp-node.eu/passport/{id} tags: - GET - public-resolution generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /passport/{id}` **Domain:** [Public Resolution](/tags/public-resolution.md) **Authentication:** **Tiered** — resolves anonymously (public view) or with a Bearer API key / capability token for a fuller view. Public, content-negotiated resolution of a Digital Product Passport by its server-assigned UUID. Lookup is by primary key only — GTIN/GRAI/serial lookups go through the GS1 Digital Link gateway (`GET /01/{gtin14}`, `GET /8003/{grai}`). **Content negotiation** — the representation is chosen by RFC 7231 §5.3.2 `Accept` q-value negotiation (highest q wins; ties broken by media-range specificity, then the client's stated order): `application/aas+json` (or bare `aas+json`) → role-filtered Asset Administration Shell environment; `application/vc+jwt` (or bare `vc+jwt`) → a signed UNTP DigitalProductPassport credential (public tier; `406 Not Acceptable` when the passport has no manufacturing facility with a country of production); `application/vc+ld+json` (or bare `vc+ld+json`) → the same credential with an embedded W3C Data Integrity proof (`ecdsa-jcs-2019`), same `406` condition; `application/dc+sd-jwt` (or the legacy `vc+sd-jwt`) → the same credential as an SD-JWT-VC for cryptographic selective disclosure (a holder presents a subset of `credentialSubject` claims), same `406` condition; `text/html` → server-rendered passport page. An absent `Accept`, or one matching only `*/*`, yields the canonical default JSON-LD (`application/ld+json`); an unsupported type is ignored. Because q-values and client order are honoured, `Accept: text/html, application/vc+jwt` selects HTML (the client's first preference), NOT `vc+jwt`. `Vary: Accept` is always set on the 200. **Access tiers** — no permission string (public endpoint). Credentials are *optional* and never produce 401/402/403 here; an invalid or foreign credential silently degrades to the public tier: - **Public** (anonymous): restricted metadata keys (for category `batteries`: `detailedPerformance`, `lifecycleAndInUse`, `circularityAndDisassembly` — masked only when present) and the owner-only key `facilityDetails` (present-as-placeholder in every non-owner response, even when the underlying metadata never contained it) carry the literal placeholder `[REDACTED - Privileged Access Required]`. Each masked key that exists in the sealed metadata keeps its true Merkle leaf hash in `proof.redactedLeaves`, so the seal stays offline-verifiable after redaction; a placeholder-valued key with no `redactedLeaves` entry was never in the sealed metadata and must be excluded when rebuilding the root. - **Legitimate interest / authority**: a capability grant token — `dpp_li_…` (tenant-issued) or `dpp_auth_…` (platform-issued, not tenant-revocable) — sent as `Authorization: Bearer ` or `?grant=`, with TENANT or PASSPORT scope covering this passport, unlocks the restricted tier-2 keys. `facilityDetails`, the facility street address and DRAFT passports stay hidden. Grant-unlocked responses add `Cache-Control: private, no-store` and `Referrer-Policy: no-referrer`. - **Owner**: a tenant **API key** (`op_dpp_token_…`, shown once at creation) belonging to the owning tenant or to a tenant bound to the passport's economic operator — sent as a Bearer token. Only API keys are matched on the public resolvers: a Console JWT login session does **not** unlock owner tier (it silently resolves as public). Owners see everything, including DRAFT passports, owner-only metadata keys and the facility street address (`manufacturingFacility.streetAddress`/`city`/`postalCode`). In the AAS representation the owner credential's API-key role drives element filtering; a grant maps to the `legitimate_interest` filter tier, anonymous to `public`. DRAFT passports are hidden from everyone but the owner (404 with a body identical to a true miss). Every resolution is recorded in the passport's access audit log with an anonymized IP. **Rate limit:** 30 requests/min/IP; its 429 body is the two-field public error shape (no `success` field). This limiter adds no headers of its own — the `x-ratelimit-*` headers still present on responses (including these 429s) belong to the global platform limit (100 req/min/IP, 600/min for known crawler user agents), which applies on top. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | The passport's server-assigned UUID (returned as id on creation and embedded as AI-21 in the SKU-level Digital Link URI). | | `grant` | query | no | string | Capability grant token (dpp_li_… legitimate-interest, dpp_auth_… authority) — the inspection-link path for QR-scanning inspectors who cannot set headers. | ## Responses - **200** — The passport in the negotiated representation. → [AasEnvironment](/schemas/AasEnvironment.md), [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) - **400** — Passport identifier missing. → [Error](/schemas/Error.md) - **404** — No passport with that UUID — or the passport is a DRAFT and the caller is not owner-tier (identical body, deliberate). → [Error](/schemas/Error.md) - **406** — The requested representation cannot be produced for this resource. → [Error](/schemas/Error.md) - **429** — Public-resolution rate limit exceeded (30 requests/min per IP; no rate-limit headers). → [Error](/schemas/Error.md) - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash # The Authorization header is optional for the public tier. curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/passport/{id}' ``` ## See also Schemas: [AasEnvironment](/schemas/AasEnvironment.md), [Error](/schemas/Error.md), [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md). ================================================================================ # FILE: /okf/operations/resolveGs1Gtin.md ================================================================================ --- type: API Endpoint title: GS1 Digital Link resolution by GTIN-14 (AI 01) description: Unified GS1 Digital Link gateway, GTIN branch. resource: https://opendpp-node.eu/01/{gtin14} tags: - GET - public-resolution generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /01/{gtin14}` **Domain:** [Public Resolution](/tags/public-resolution.md) **Authentication:** **Tiered** — resolves anonymously (public view) or with a Bearer API key / capability token for a fuller view. Unified GS1 Digital Link gateway, GTIN branch. The GTIN-14 is matched against `metadata.gtin`, `metadata.grai`, or the passport's `productId`. On tenant workspaces (`https://{tenant}.opendpp-node.eu`) the lookup is scoped to that tenant — an unknown subdomain returns 404. Without a tenant scope, a GTIN matching more than one passport is rejected with 400 (ambiguous); disambiguate via a brand subdomain (the `?subdomain=` query override is honoured in non-production environments only). Content negotiation (RFC 7231 §5.3.2 `Accept` q-value negotiation; JSON-LD default / `application/aas+json` / `application/vc+jwt` / `application/vc+ld+json` / `application/dc+sd-jwt` / `text/html`, `Vary: Accept` always set), access tiers (public / `dpp_li_…`·`dpp_auth_…` grant via Bearer or `?grant=` / owner = a tenant **API key** sent as a Bearer token — Console JWT login sessions do **not** unlock owner tier), DRAFT hiding, access-audit logging (anonymized IP), and grant response headers (`Cache-Control: private, no-store`, `Referrer-Policy: no-referrer`) are identical to `GET /passport/{id}` — see that operation for the full tier semantics. No permission string (public endpoint); invalid credentials silently degrade to the public tier, never 401/403. The gateway also accepts additional GS1 AI key/value path pairs after the GTIN; the only one acted on is AI 21 (serial) — documented separately as `GET /01/{gtin14}/21/{serial}`. (The underlying route is `GET /{ai}/*`; AI prefixes other than `01` and `8003` get a 400.) This resolver handles only the **UNCOMPRESSED** GS1 Digital Link grammar; a **compressed** Digital Link (its AI data encoded as a base64url blob) is detected and rejected with a clear 400 that points to the uncompressed form. **Rate limit:** 30 requests/min/IP; two-field 429 body without `success`. The limiter adds no headers of its own — `x-ratelimit-*` headers on responses come from the global platform limit (100 req/min/IP), which applies on top. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `gtin14` | path | yes | string | GTIN-14: exactly 14 digits with a valid GS1 modulo-10 check digit (the check digit is validated server-side — the pattern alone is not sufficient). | | `grant` | query | no | string | Capability grant token (dpp_li_… / dpp_auth_…); equivalent to Authorization: Bearer. | ## Responses - **200** — The matched passport in the negotiated representation (same envelope as GET /passport/{id}). → [AasEnvironment](/schemas/AasEnvironment.md), [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) - **400** — Invalid GTIN-14 (must be 14 digits with a valid modulo-10 check digit) or — when no tenant scope is in play and no AI-21 serial was given — an ambiguous lookup… → [Error](/schemas/Error.md) - **404** — No passport matches the identifier (content-negotiated: HTML page for Accept: text/html, JSON otherwise; Vary: Accept set), a DRAFT match was hidden from a non… → [Error](/schemas/Error.md) - **406** — The requested representation cannot be produced for this resource. → [Error](/schemas/Error.md) - **429** — Public-resolution rate limit exceeded (30 requests/min per IP; no rate-limit headers). → [Error](/schemas/Error.md) - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash # The Authorization header is optional for the public tier. curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/01/{gtin14}' ``` ## See also Schemas: [AasEnvironment](/schemas/AasEnvironment.md), [Error](/schemas/Error.md), [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md). ================================================================================ # FILE: /okf/operations/resolveGs1GtinSerial.md ================================================================================ --- type: API Endpoint title: GS1 Digital Link serialised-item redirect (AI 01 + AI 21) description: GS1 Digital Link resolution of an *individual serialised item*. resource: https://opendpp-node.eu/01/{gtin14}/21/{serial} tags: - GET - public-resolution generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /01/{gtin14}/21/{serial}` **Domain:** [Public Resolution](/tags/public-resolution.md) **Authentication:** **Public** — no authentication required. GS1 Digital Link resolution of an *individual serialised item*. This path never returns a document directly — on success it issues a `302` redirect (the query string, including `?grant=`, is preserved on the `Location` URL): 1. If the GTIN resolves to a SKU/type passport that has a serialised battery unit whose `serialNumber` equals the AI-21 value → `302` to `/unit/{unitId}` (per-unit view). 2. Otherwise (legacy fallback) the AI-21 value is matched against the passport UUID, `metadata.serialNumber`, or `metadata["21"]`; if a passport matches → `302` to `/passport/{passportId}`. 3. Otherwise → `404` (content-negotiated). The ambiguity check of the bare-GTIN branch is skipped when an AI-21 serial is present. The redirect handler itself never evaluates credentials — access tiers (owner / grant / public) apply at the redirect target; carry the grant in `?grant=` (preserved across the redirect) or re-send the `Authorization` header to the target. On tenant subdomains the lookup is scoped to that tenant (unknown subdomain → 404, JSON only). No permission string (public endpoint). **Rate limit:** 30 requests/min/IP (two-field 429 body without `success`). The limiter adds no headers of its own — `x-ratelimit-*` headers come from the global platform limit, which applies on top — and the redirect target counts as a second request against both. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `gtin14` | path | yes | string | GTIN-14: exactly 14 digits with a valid GS1 modulo-10 check digit (validated server-side). | | `serial` | path | yes | string | GS1 AI-21 serial. | | `grant` | query | no | string | Capability grant token. | ## Responses - **302** — Redirect to the resolved resource. - **400** — Invalid GTIN-14 (format / modulo-10 check digit). → [Error](/schemas/Error.md) - **404** — Neither a serialised unit nor a fallback passport matches (content-negotiated HTML/JSON, Vary: Accept), or unknown tenant subdomain (JSON only). → [Error](/schemas/Error.md) - **429** — Public-resolution rate limit exceeded (30 requests/min per IP; no rate-limit headers). → [Error](/schemas/Error.md) - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -X GET 'https://opendpp-node.eu/01/{gtin14}/21/{serial}' ``` ## See also Schemas: [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/resolveGs1Grai.md ================================================================================ --- type: API Endpoint title: GS1 Digital Link resolution by GRAI (AI 8003) description: Unified GS1 Digital Link gateway, GRAI branch (Global Returnable Asset Identifier). resource: https://opendpp-node.eu/8003/{grai} tags: - GET - public-resolution generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /8003/{grai}` **Domain:** [Public Resolution](/tags/public-resolution.md) **Authentication:** **Tiered** — resolves anonymously (public view) or with a Bearer API key / capability token for a fuller view. Unified GS1 Digital Link gateway, GRAI branch (Global Returnable Asset Identifier). The GRAI is matched against `metadata.gtin`, `metadata.grai`, or the passport's `productId`. Everything else — content negotiation (JSON-LD default / `application/aas+json` / `application/vc+jwt` / `application/vc+ld+json` / `application/dc+sd-jwt` / `text/html`, `Vary: Accept`), access tiers (public / grant `dpp_li_…`·`dpp_auth_…` via Bearer or `?grant=` / owner = tenant API key as Bearer, never a Console JWT session), DRAFT hiding, tenant-subdomain scoping, the no-tenant-scope ambiguity 400, access-audit logging, grant response headers, and the 30 req/min/IP rate limit (two-field 429 body without `success`; the limiter adds no headers of its own — `x-ratelimit-*` headers come from the global 100 req/min/IP limit, which applies on top) — is identical to `GET /01/{gtin14}`; see that operation and `GET /passport/{id}` for full semantics. An additional `/21/{serial}` AI pair after the GRAI behaves exactly like `GET /01/{gtin14}/21/{serial}` (302 redirect to `/unit/{id}` or `/passport/{id}`). No permission string (public endpoint). ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `grai` | path | yes | string | GRAI: a 14-digit numeric asset identifier with a valid GS1 modulo-10 check digit (validated server-side), followed by an optional alphanumeric serial component… | | `grant` | query | no | string | Capability grant token (dpp_li_… / dpp_auth_…); equivalent to Authorization: Bearer. | ## Responses - **200** — The matched passport in the negotiated representation (same envelope as GET /passport/{id}). → [AasEnvironment](/schemas/AasEnvironment.md), [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) - **400** — Invalid GRAI (format / check digit) or — without tenant scope and AI-21 serial — an ambiguous lookup. → [Error](/schemas/Error.md) - **404** — No passport matches (content-negotiated HTML/JSON, Vary: Accept), DRAFT hidden from non-owner, or unknown tenant subdomain (JSON only). → [Error](/schemas/Error.md) - **406** — The requested representation cannot be produced for this resource. → [Error](/schemas/Error.md) - **429** — Public-resolution rate limit exceeded (30 requests/min per IP; no rate-limit headers). → [Error](/schemas/Error.md) - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash # The Authorization header is optional for the public tier. curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/8003/{grai}' ``` ## See also Schemas: [AasEnvironment](/schemas/AasEnvironment.md), [Error](/schemas/Error.md), [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md). ================================================================================ # FILE: /okf/operations/resolvePublicBatteryUnit.md ================================================================================ --- type: API Endpoint title: Resolve an individual serialised battery unit description: Public, content-negotiated view of one individual serialised unit (battery) by its unit UUID, including the embedded SKU/type passport (ofModel, masked by the same tier rules as GET /passport/{id}). resource: https://opendpp-node.eu/unit/{id} tags: - GET - public-resolution generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /unit/{id}` **Domain:** [Public Resolution](/tags/public-resolution.md) **Authentication:** **Tiered** — resolves anonymously (public view) or with a Bearer API key / capability token for a fuller view. Public, content-negotiated view of one individual serialised unit (battery) by its unit UUID, including the embedded SKU/type passport (`ofModel`, masked by the same tier rules as `GET /passport/{id}`). **Content negotiation:** `Accept` containing `application/vc+jwt` (or bare `vc+jwt`) → a signed PER-UNIT (item-granularity) UNTP DigitalProductPassport credential (public tier; `406 Not Acceptable` when the unit's type passport has no manufacturing facility with a country of production); `application/vc+ld+json` (or bare `vc+ld+json`) → the same per-unit credential with an embedded `ecdsa-jcs-2019` Data Integrity proof, same `406`; `text/html` → server-rendered unit page; everything else → JSON-LD (`application/ld+json`). No AAS representation on this route. `Vary: Accept` always set on the 200. The `410` tombstone check (below) precedes content negotiation, so a recycled/ceased unit never yields a `vc+jwt` or `vc+ld+json`. **Per-unit telemetry is never public** (Annex XIII(2)-(4)): anonymous responses omit `currentState`/`dynamicData` and instead carry a `restrictedData` notice with a `/request-access` pointer. An owner credential — a tenant **API key** (`op_dpp_token_…`) of the owning or operator-bound tenant, sent as a Bearer token (a Console JWT login session does **not** unlock owner tier) — or a valid grant token (`dpp_li_…`/`dpp_auth_…` as Bearer or `?grant=`; TENANT, PASSPORT or UNIT scope) unlocks `currentState` and `dynamicData` — up to the 500 most recent events, newest first. Invalid credentials silently degrade to the public tier (never 401/402/403). Grant-unlocked responses add `Cache-Control: private, no-store` + `Referrer-Policy: no-referrer`. No permission string (public endpoint). **Tombstone:** once the unit's status is `RECYCLED` (or `ceasedAt` is set) this URL answers `410 Gone` with a minimal tombstone for everyone — grants and owner credentials do NOT override it (the owning tenant retains internal access via `GET /api/v1/units/{id}`). Every resolution is access-audit-logged with an anonymized IP. **Rate limit:** 30 requests/min/IP (two-field 429 body without `success`). The limiter adds no headers of its own — `x-ratelimit-*` headers come from the global platform limit, which applies on top. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | The battery unit's server-assigned UUID (AI-21 serial resolution via GET /01/{gtin14}/21/{serial} redirects here). | | `grant` | query | no | string | Capability grant token (dpp_li_… / dpp_auth_…); equivalent to Authorization: Bearer. | ## Responses - **200** — The unit document in the negotiated representation. → [PublicBatteryUnitJsonLd](/schemas/PublicBatteryUnitJsonLd.md) - **404** — No unit with that id (a malformed UUID also resolves to this 404). → [Error](/schemas/Error.md) - **406** — The requested representation cannot be produced for this resource. → [Error](/schemas/Error.md) - **410** — Gone — the unit was RECYCLED (or ceasedAt is set): the battery passport has ceased to exist. → [BatteryUnitTombstoneJsonLd](/schemas/BatteryUnitTombstoneJsonLd.md) - **429** — Public-resolution rate limit exceeded (30 requests/min per IP; no rate-limit headers). → [Error](/schemas/Error.md) - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash # The Authorization header is optional for the public tier. curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/unit/{id}' ``` ## See also Schemas: [BatteryUnitTombstoneJsonLd](/schemas/BatteryUnitTombstoneJsonLd.md), [Error](/schemas/Error.md), [PublicBatteryUnitJsonLd](/schemas/PublicBatteryUnitJsonLd.md). ================================================================================ # FILE: /okf/operations/getSealCaCertificate.md ================================================================================ --- type: API Endpoint title: Download the platform seal-CA certificate (PEM) description: Downloads the platform seal-CA certificate as PEM. resource: https://opendpp-node.eu/.well-known/opendpp-seal-ca.pem tags: - GET - eidas-keys generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /.well-known/opendpp-seal-ca.pem` **Domain:** [eIDAS Keys](/tags/eidas-keys.md) **Authentication:** **Public** — no authentication required. Downloads the platform seal-CA certificate as PEM. Third parties pin this CA to validate the `x5c` certificate chains embedded in sealed-passport `proof` blocks — the chain's leaf certificate binds a tenant's signing key to its legal identity (the advanced-seal creator identification; the seal is an *advanced*, not qualified, electronic seal). The certificate is provisioned server-side on first use. No authentication, no permission (public endpoint). Successful responses carry `Cache-Control: public, max-age=3600`. Like every documented path except `/health`, a request on an unknown tenant workspace host receives a platform-level JSON 404 before this handler runs. **Rate limit:** 30 requests/min/IP — note that this route's 429 body carries ONLY `{"error": "Too Many Requests"}` (no `message`, no `success`), unlike the other public resolvers. The global platform limit (100 req/min/IP) applies on top: a global-limit 429 carries the platform's default `{statusCode, error, message}` body instead, and the global limiter's `x-ratelimit-*` headers appear on every response from this route. Returns `503` if the seal CA cannot be provisioned or loaded. ## Responses - **200** — The CA certificate, PEM-encoded. - **429** — Rate limited (30/min/IP). - **503** — Seal CA not available (provisioning/load failure). → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -X GET 'https://opendpp-node.eu/.well-known/opendpp-seal-ca.pem' ``` ## See also Schemas: [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/getSectorSchema.md ================================================================================ --- type: API Endpoint title: Get the ESPR metadata schema for a product category description: Returns the machine-readable ESPR metadata schema for a product category. resource: https://opendpp-node.eu/api/v1/schemas/{category} tags: - GET - schemas-vocabulary generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/schemas/{category}` **Domain:** [Schemas & Vocabulary](/tags/schemas-vocabulary.md) **Authentication:** **Public** — no authentication required. Returns the machine-readable ESPR `metadata` schema for a product category. **Default representation** (any `Accept` NOT containing `application/ld+json`): the category's JSON Schema **draft-07** document, served as `application/schema+json`, with each known field annotated server-side with a plain-English `description` (the annotations are AJV-ignored — validation behavior is unchanged). **With `Accept: application/ld+json`:** a small JSON-LD `@context` for the category vocabulary instead. Note: the route does not set `Vary: Accept`. The category path segment is lower-cased before lookup. Machine-readable schemas exist for **5** of the 9 ESPR categories: `textiles`, `batteries`, `electronics`, `chemicals`, `construction`. The remaining 4 categories accepted by passport metadata validation (`cosmetics`, `toys`, `iron-steel`, `aluminium`) are validated by built-in server rules and currently return `404` from this endpoint. No authentication, no permission (public endpoint). No custom rate limiter — only the global platform limit applies (100 req/min/IP, standard `x-ratelimit-*` headers). Like every documented path except `/health`, a request on an unknown tenant workspace host receives a platform-level JSON 404 (`No tenant company found for subdomain: …`, no `success` field) before this handler runs. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `category` | path | yes | string | ESPR product category (case-insensitive). | ## Responses - **200** — The category schema (default) or its JSON-LD vocabulary context (Accept: application/ld+json). → [SectorJsonSchemaDocument](/schemas/SectorJsonSchemaDocument.md), [SectorVocabularyContext](/schemas/SectorVocabularyContext.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. ## Example ```bash curl -s \ -X GET 'https://opendpp-node.eu/api/v1/schemas/{category}' ``` ## See also Schemas: [SectorJsonSchemaDocument](/schemas/SectorJsonSchemaDocument.md), [SectorVocabularyContext](/schemas/SectorVocabularyContext.md). ================================================================================ # FILE: /okf/operations/getDppJsonLdContext.md ================================================================================ --- type: API Endpoint title: Canonical resolvable JSON-LD context for passport & unit documents description: Serves the stable, resolvable W3C JSON-LD @context (application/ld+json) that every public passport and battery-unit JSON-LD document references in its @context array — this is the context to dereference when expanding OpenDPP JSON-LD. resource: https://opendpp-node.eu/contexts/dpp/v1 tags: - GET - schemas-vocabulary generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /contexts/dpp/v1` **Domain:** [Schemas & Vocabulary](/tags/schemas-vocabulary.md) **Authentication:** **Public** — no authentication required. Serves the stable, resolvable W3C JSON-LD `@context` (`application/ld+json`) that **every** public passport and battery-unit JSON-LD document references in its `@context` array — this is the context to dereference when expanding OpenDPP JSON-LD. It declares `@vocab: https://opendpp-node.eu/ns/dpp#` (so even dynamic metadata keys expand under the OpenDPP namespace and are never silently dropped by a strict JSON-LD processor) plus explicit term mappings for the core DPP/unit vocabulary (`DigitalProductPassport`, `BatteryUnit`, `economicOperator`, `manufacturingFacility`, `metadata`, `digitalSeal`, `signingPublicKey`, `proof`, `status`, `MerkleTreeAttestationProof`). Cacheable (`Cache-Control: public, max-age=86400`). (The separate `/context/v1` serves an older, fixed term-only list and is **not** the context emitted documents point to.) No authentication, no permission (public endpoint). No custom rate limiter — only the global platform limit applies (100 req/min/IP, standard `x-ratelimit-*` headers). ## Responses - **200** — The canonical @vocab-based JSON-LD context document (fixed content). → [DppVocabContextDocument](/schemas/DppVocabContextDocument.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. ## Example ```bash curl -s \ -X GET 'https://opendpp-node.eu/contexts/dpp/v1' ``` ## See also Schemas: [DppVocabContextDocument](/schemas/DppVocabContextDocument.md). ================================================================================ # FILE: /okf/operations/getJsonLdContext.md ================================================================================ --- type: API Endpoint title: W3C JSON-LD context document for passport terms (secondary, fixed term list) description: "Serves a static W3C JSON-LD @context document (application/ld+json) for the core Digital Product Passport term vocabulary: maps the DPP terms to https://opendpp-node.eu/ns/dpp#… IRIs and createdAt/updatedAt to schema.org dateCreated/dateMo…" resource: https://opendpp-node.eu/context/v1 tags: - GET - schemas-vocabulary generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /context/v1` **Domain:** [Schemas & Vocabulary](/tags/schemas-vocabulary.md) **Authentication:** **Public** — no authentication required. Serves a static W3C JSON-LD `@context` document (`application/ld+json`) for the core Digital Product Passport term vocabulary: maps the DPP terms to `https://opendpp-node.eu/ns/dpp#…` IRIs and `createdAt`/`updatedAt` to schema.org `dateCreated`/`dateModified`. This is a **secondary** fixed term list — the context that public passport/unit JSON-LD documents actually reference is the `@vocab`-based one at `GET /contexts/dpp/v1`; dereference that when expanding OpenDPP JSON-LD. No authentication, no permission (public endpoint). No custom rate limiter — only the global platform limit applies (100 req/min/IP, standard `x-ratelimit-*` headers). Like every documented path except `/health`, a request on an unknown tenant workspace host receives a platform-level JSON 404 before this handler runs. ## Responses - **200** — The JSON-LD context document (fixed content). → [DppJsonLdContextDocument](/schemas/DppJsonLdContextDocument.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. ## Example ```bash curl -s \ -X GET 'https://opendpp-node.eu/context/v1' ``` ## See also Schemas: [DppJsonLdContextDocument](/schemas/DppJsonLdContextDocument.md). ================================================================================ # FILE: /okf/operations/getHealth.md ================================================================================ --- type: API Endpoint title: Service health check description: Liveness probe. resource: https://opendpp-node.eu/health tags: - GET - service generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /health` **Domain:** [Service](/tags/service.md) **Authentication:** **Public** — no authentication required. Liveness probe. Always returns 200 with the service identity, the current server time (ISO 8601 UTC with milliseconds), and the running build identity (`apiVersion`/`commit`/`builtAt` — the same fields as `GET /api/v1/version`). No authentication, no permission. **Exempt from the platform rate limit** so a monitor or uptime check can poll it freely — it carries no `x-ratelimit-*` headers. This is the one path exempt from tenant-subdomain resolution — it answers 200 on any host. ## Responses - **200** — Service is up. → [HealthStatus](/schemas/HealthStatus.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. ## Example ```bash curl -s \ -X GET 'https://opendpp-node.eu/health' ``` ## See also Schemas: [HealthStatus](/schemas/HealthStatus.md). ================================================================================ # FILE: /okf/operations/getApiVersion.md ================================================================================ --- type: API Endpoint title: Running API contract version & build identity description: Returns the SemVer of the public API contract currently served (apiVersion), plus the source build identity (commit, builtAt). resource: https://opendpp-node.eu/api/v1/version tags: - GET - service generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/version` **Domain:** [Service](/tags/service.md) **Authentication:** **Public** — no authentication required. Returns the SemVer of the public API contract currently served (`apiVersion`), plus the source build identity (`commit`, `builtAt`). The contract's MAJOR equals the `/api/v1` URL major; a breaking change ships as a new `/api/v1`-style major (`/api/v2`), never as an edit to this contract — so a stable `apiVersion` major is a safe thing for an integration or a generated SDK to pin to. `commit`/`builtAt` read `"unknown"` when a build did not inject them. No authentication, no permission; subject only to the global platform rate limit (100 req/min/IP anonymous, higher for authenticated callers; standard `x-ratelimit-*` headers on responses). ## Responses - **200** — The running API contract version and build identity. → [ServiceVersion](/schemas/ServiceVersion.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. ## Example ```bash curl -s \ -X GET 'https://opendpp-node.eu/api/v1/version' ``` ## See also Schemas: [ServiceVersion](/schemas/ServiceVersion.md). ================================================================================ # FILE: /okf/operations/mintGtinCheckDigit.md ================================================================================ --- type: API Endpoint title: Compute a GTIN check digit from a company prefix + item reference description: "The actionable counterpart to the non-GS1 ingest advisory: given the GS1 company prefix your organisation legally owns plus an item reference, OpenDPP computes the GS1 mod-10 check digit and returns the resulting 14-digit GTIN + a Digital…" resource: https://opendpp-node.eu/api/v1/gs1/gtin tags: - POST - public-resolution generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/gs1/gtin` **Domain:** [Public Resolution](/tags/public-resolution.md) **Authentication:** **Public** — no authentication required. The actionable counterpart to the non-GS1 ingest advisory: given the **GS1 company prefix your organisation legally owns** plus an item reference, OpenDPP computes the GS1 **mod-10 check digit** and returns the resulting 14-digit GTIN + a Digital Link preview. Set the GTIN as a passport `productId` to get a scannable GS1 Digital Link. **It ONLY completes the check digit** — it never allocates a GS1 company prefix or asserts ownership (a real GTIN requires a prefix licensed to you by GS1). `gs1CompanyPrefix` is REQUIRED; a request with none is refused (**400**). `gs1CompanyPrefix + itemRef` must be exactly **13 digits** (the check digit forms the 14th) and both must be digit strings, else **400**. Public + stateless (pure arithmetic; no tenant data). No authentication required. **Rate limit (changed in 1.12.0):** an **anonymous** caller gets **2 requests/min per IP** — a per-route cap that replaces the global ceiling. Send an `Authorization` header (any valid API key) and the normal ladder applies instead: the global authenticated ceiling, with your per-key tier bucket underneath it. Standard `x-ratelimit-*` headers; **429** with `retry-after` when exceeded. ## Request body A JSON body is required. ```json { "gs1CompanyPrefix": "0950110153", "itemRef": "000" } ``` ## Responses - **200** — The computed GTIN + Digital Link preview. - **400** — gs1CompanyPrefix missing (we never fabricate a GTIN), non-digit input, or prefix + itemRef not exactly 13 digits. ## Example ```bash curl -s \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/gs1/gtin' \ --data '{"gs1CompanyPrefix":"0950110153","itemRef":"000"}' ``` ================================================================================ # FILE: /okf/operations/decodeGs1.md ================================================================================ --- type: API Endpoint title: Decode GS1 scan data / element string / Digital Link into structured AIs + HRI description: Decodes raw scanner output — AIM-symbology-prefixed scan data (e.g. ]Q1https://id.gs1.org/01/09501101532007/21/VM-1, ]C1010950…), a bracketed GS1 element string ((01)09501101532007(21)VM-1), or a Digital Link URI — into its structured Appl… resource: https://opendpp-node.eu/api/v1/gs1/decode tags: - POST - public-resolution generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/gs1/decode` **Domain:** [Public Resolution](/tags/public-resolution.md) **Authentication:** **Public** — no authentication required. Decodes raw scanner output — AIM-symbology-prefixed **scan data** (e.g. `]Q1https://id.gs1.org/01/09501101532007/21/VM-1`, `]C1010950…`), a bracketed GS1 **element string** (`(01)09501101532007(21)VM-1`), or a **Digital Link** URI — into its structured Application Identifiers, the Human-Readable Interpretation (HRI), and a Digital Link that resolves on this node. Parsing is performed by GS1's authoritative Barcode Syntax Engine (vendored WASM), so check digits and the AI grammar are validated, not approximated. **Public + stateless** — no permission and no tenant data is touched; it complements the public resolver. Supply **exactly one** of `scanData`, `elementString`, `digitalLink`; zero or more than one returns 400. After decoding, `GET` the returned `digitalLinkUri` (the canonical path rehosted on this node) to resolve the passport/unit. **Errors:** missing/multiple/over-long input, or a value GS1's grammar rejects, returns **400** (`Provide exactly one of: scanData, elementString, digitalLink` or `Not a valid GS1 : `); **503** if the engine is unavailable. **Rate limit (changed in 1.12.0):** an **anonymous** caller gets **2 requests/min per IP** — a per-route cap that replaces the global ceiling, so this endpoint stays a convenience for integrators rather than a free scripted service. Send an `Authorization` header (any valid API key) and the normal ladder applies instead: the global authenticated ceiling, with your per-key tier bucket underneath it. Standard `x-ratelimit-*` headers on both paths; **429** with `retry-after` when exceeded. ## Request body A JSON body is required. ## Responses - **200** — Decoded GS1 data. - **400** — Missing/multiple inputs, over-long input, or a value GS1's grammar rejects. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **503** — The GS1 Syntax Engine (WASM) could not be loaded. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -X POST 'https://opendpp-node.eu/api/v1/gs1/decode' ``` ## See also Schemas: [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/decodeGs1Batch.md ================================================================================ --- type: API Endpoint title: Batch-decode many GS1 scans / element strings / Digital Links in one request description: Batch form of POST /api/v1/gs1/decode for line-side / warehouse stations capturing many scans per second. resource: https://opendpp-node.eu/api/v1/gs1/decode/batch tags: - POST - public-resolution generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/gs1/decode/batch` **Domain:** [Public Resolution](/tags/public-resolution.md) **Authentication:** **Public** — no authentication required. Batch form of `POST /api/v1/gs1/decode` for line-side / warehouse stations capturing many scans per second. Send `{ "items": [ … ] }` (≤200), each item exactly one of `scanData`/`elementString`/`digitalLink`, and receive a `results` array aligned to input order — each entry either a decoded scan (`ok: true`, the same fields as the single-scan 200 minus `success`) or an error (`ok: false` + `error`). **Partial-success:** one bad item never fails the batch — the request returns **200** and per-item failures are reported in place. Parsing uses GS1's authoritative Barcode Syntax Engine (vendored WASM). **Public + stateless** (no permission, no tenant data). **Errors:** a missing/empty/non-array `items`, or more than 200 items, returns **400**; a body over the 256 KiB route cap returns **413**; **503** if the engine is unavailable. **Rate limit (changed in 1.12.0):** an **anonymous** caller gets **2 requests/min per IP** — a per-route cap that replaces the global ceiling, so this endpoint stays a convenience for integrators rather than a free scripted service. Send an `Authorization` header (any valid API key) and the normal ladder applies instead: the global authenticated ceiling, with your per-key tier bucket underneath it. Standard `x-ratelimit-*` headers on both paths; **429** with `retry-after` when exceeded. ## Request body A JSON body is required. ```json { "items": [ { "scanData": "]Q1https://id.gs1.org/01/09501101532007/21/VM-LFP100-26-1" }, { "elementString": "(01)09501101532007" }, { "digitalLink": "not-a-valid-link" } ] } ``` ## Responses - **200** — Per-item decode results aligned to input order (partial-success — one bad item never fails the batch). → [Gs1BatchDecodeResult](/schemas/Gs1BatchDecodeResult.md) - **400** — Missing/empty/non-array items, or more than 200 items. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **503** — The GS1 Syntax Engine (WASM) could not be loaded. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/gs1/decode/batch' \ --data '{"items":[{"scanData":"]Q1https://id.gs1.org/01/09501101532007/21/VM-LFP100-26-1"},{"elementString":"(01)09501101532007"},{"digitalLink":"not-a-valid-link"}]}' ``` ## See also Schemas: [Error](/schemas/Error.md), [Gs1BatchDecodeResult](/schemas/Gs1BatchDecodeResult.md). ================================================================================ # FILE: /okf/operations/getPassportQrCode.md ================================================================================ --- type: API Endpoint title: Export a print-grade GS1 Digital Link QR code for a passport description: Renders the passport's GS1 Digital Link URI (its digitalLinkUri, e.g. https://opendpp-node.eu/01/09501101530003) as a print-grade QR code and returns it as a binary file download. resource: https://opendpp-node.eu/api/v1/passports/{id}/qr tags: - GET - qr-codes generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/passports/{id}/qr` **Domain:** [QR Codes](/tags/qr-codes.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Renders the passport's GS1 Digital Link URI (its `digitalLinkUri`, e.g. `https://opendpp-node.eu/01/09501101530003`) as a print-grade QR code and returns it as a binary file download. The printed carrier resolves through the public GS1 gateway. **Permission:** `passport:read` (read-only — subscription status is **not** checked on `:read` permissions, so this endpoint never returns 402). Works with a Bearer API key, a Bearer JWT, or an authenticated browser session — plain same-origin `` downloads are supported. **Identifier resolution:** `{id}` is matched first against the passport UUID, then against the caller-supplied `productId` (GTIN-14/GRAI/SKU), always scoped to your tenant. Credentials scoped to an Economic Operator receive **403** (`Your access is restricted to Economic Operator: `) when the passport belongs to a different operator. **QR rendering:** 4-module quiet zone (GS1 guidance); error-correction level per `ecl` (default `Q`, the GS1 recommendation for product labels); `size` is **clamped** to 128–2048 px — out-of-range values are clamped to the nearest bound, not rejected, and fractional values are truncated. The response carries `Content-Disposition: attachment; filename="qr-.png"` (or `.svg`); the filename base is the passport's `productId` with characters outside `[A-Za-z0-9._-]` replaced by `_`, truncated to 80 characters. **Errors:** an invalid query option returns **400** with one of these exact messages: `format must be png or svg`, `size must be a number`, `ecl must be M, Q or H`. An unknown passport returns **404** with message `Passport not found under your Tenant workspace`. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Passport UUID, or the caller-supplied productId (GTIN-14/GRAI/SKU) as a fallback. | | `format` | query | no | string | Output image format. | | `size` | query | no | integer | Rendered width in pixels (PNG) / SVG width attribute. | | `ecl` | query | no | string | QR error-correction level: M (~15% recovery), Q (~25%, GS1 product-label guidance, default) or H (~30%). | | `hri` | query | no | boolean | When 1/true, renders the GS1 Human-Readable Interpretation (the bracketed AI string, e.g. (01) 09501101530003 (21) BAT-2026-000123) as vector text beneath the… | ## Responses - **200** — QR code image encoding the passport's digitalLinkUri. - **400** — Invalid query option. → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/passports/{id}/qr' ``` ## See also Schemas: [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/bulkExportPassportLabels.md ================================================================================ --- type: API Endpoint title: Bulk-export print-grade QR labels for many passports as a ZIP description: 'Renders a GS1 Digital Link QR code for each of the supplied passports and returns them as a single application/zip download (Content-Disposition: attachment; filename="labels.zip") — the export counterpart to the bulk import.' resource: https://opendpp-node.eu/api/v1/passports/labels tags: - POST - qr-codes generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/passports/labels` **Domain:** [QR Codes](/tags/qr-codes.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Renders a GS1 Digital Link QR code for each of the supplied passports and returns them as a single `application/zip` download (`Content-Disposition: attachment; filename="labels.zip"`) — the export counterpart to the bulk import. One image entry per resolved passport, named `.` (characters outside `[A-Za-z0-9._-]` replaced by `_`, truncated to 80 chars; duplicate names get a `-2`, `-3`, … suffix), plus a `manifest.json` listing what was `included` and `skipped`. **Permission:** `passport:read` (read-only — no subscription/402 gate, and NOT subject to the programmatic API-write entitlement). **Partial success:** an id that is unknown, not owned by your tenant, or outside an operator-scoped key's bound operator is **skipped and reported** in `manifest.json` (`{ id, reason }`) — it never fails the whole batch. Only the caller's own passports resolve, so this cannot enumerate another tenant's catalog. **Limits:** at most **200** ids per call (mirrors the bulk-import cap); more returns **400** pointing at the async export. `hri: true` requires `format: "svg"` (same constraint as the single QR). `size` is clamped to 128–2048. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Request body A JSON body is required. ```json { "ids": [ "09501101530003", "9b2fa884-3c1d-4e0a-9f6b-2d7c5a1e8b40" ], "format": "svg", "hri": true } ``` ## Responses - **200** — A ZIP archive of QR images (one per resolved passport) plus a manifest.json reporting included/skipped ids. - **400** — Empty/oversize ids (> 200), an invalid format/size/ecl, or hri: true without format: "svg". → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/passports/labels' \ --data '{"ids":["09501101530003","9b2fa884-3c1d-4e0a-9f6b-2d7c5a1e8b40"],"format":"svg","hri":true}' ``` ## See also Schemas: [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/getBatteryUnitQrCode.md ================================================================================ --- type: API Endpoint title: Export a print-grade QR code for an individual battery unit description: Renders the battery unit's GS1 Digital Link URI as a print-grade QR code — the AI-21 path segment carries the unit's real physical serial number (e.g. https://opendpp-node.eu/01/09501101530003/21/BAT-2026-000123). resource: https://opendpp-node.eu/api/v1/units/{id}/qr tags: - GET - qr-codes generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/units/{id}/qr` **Domain:** [QR Codes](/tags/qr-codes.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Renders the battery unit's GS1 Digital Link URI as a print-grade QR code — the AI-21 path segment carries the unit's **real physical serial number** (e.g. `https://opendpp-node.eu/01/09501101530003/21/BAT-2026-000123`). This is the carrier each individual battery must wear (per-unit passports, per the EU Battery Regulation). **Permission:** `battery:read` (read-only — subscription status is **not** checked on `:read` permissions, so this endpoint never returns 402). Works with a Bearer API key, a Bearer JWT, or an authenticated browser session. **Identifier resolution:** `{id}` is the BatteryUnit **UUID only** — unlike the passport QR route there is **no** serial-number fallback. Lookup is tenant-scoped. Credentials scoped to an Economic Operator receive **403** (`Your access is restricted to Economic Operator: `) when the unit's parent passport belongs to a different operator. **QR rendering:** identical pipeline to the passport QR export — 4-module quiet zone, `ecl` default `Q`, `size` clamped to 128–2048 px (clamped, not rejected; fractions truncated). The response carries `Content-Disposition: attachment; filename="qr-.png"` (or `.svg`); the filename base is the unit's `serialNumber` with characters outside `[A-Za-z0-9._-]` replaced by `_`, truncated to 80 characters. **Errors:** an invalid query option returns **400** with one of these exact messages: `format must be png or svg`, `size must be a number`, `ecl must be M, Q or H`. An unknown unit returns **404** with message `Battery unit not found under your Tenant workspace`. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | BatteryUnit UUID (primary key). | | `format` | query | no | string | Output image format. | | `size` | query | no | integer | Rendered width in pixels (PNG) / SVG width attribute. | | `ecl` | query | no | string | QR error-correction level: M (~15% recovery), Q (~25%, GS1 product-label guidance, default) or H (~30%). | | `hri` | query | no | boolean | When 1/true, renders the GS1 Human-Readable Interpretation (the bracketed AI string, e.g. (01) 09501101530003 (21) BAT-2026-000123) as vector text beneath the… | ## Responses - **200** — QR code image encoding the unit's digitalLinkUri (AI-21 = real physical serial). - **400** — Invalid query option. → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/units/{id}/qr' ``` ## See also Schemas: [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/listMaterials.md ================================================================================ --- type: API Endpoint title: List the platform-curated material vocabulary description: Lists active entries from the platform-global material vocabulary that powers the searchable material/fiber/chemistry pickers in the passport form. resource: https://opendpp-node.eu/api/v1/materials tags: - GET - schemas-vocabulary generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/materials` **Domain:** [Schemas & Vocabulary](/tags/schemas-vocabulary.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Lists active entries from the platform-global material vocabulary that powers the searchable material/fiber/chemistry pickers in the passport form. This is shared reference data, deliberately **not** tenant-scoped, so DPP data stays comparable across tenants. **Auth:** any authenticated session — Bearer API key, Bearer JWT, or browser session. **No specific permission string is required** and subscription status is not checked, so this endpoint never returns 402. On a tenant-subdomain host, credentials belonging to a different tenant receive **403** with message `Cross-tenant access blocked.`. **Filtering & ordering:** `kind` filters by vocabulary kind — an unrecognized value is **silently ignored** (the filter simply isn't applied; no 400). `search` is a trimmed, case-insensitive substring match on `name` (blank values ignored). Only active entries are returned, ordered by `kind` ascending then `name` ascending. `limit` is clamped to 1–1000 (default 1000); there is no pagination. **Envelope caveat:** the 200 body is `{ "materials": [...] }` — there is **no `success` field** on this endpoint. **Curation:** this vocabulary is curated by the platform operator — the API is read-only for tenant credentials. Free-text material values in passport metadata remain allowed but are never auto-added to this vocabulary. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `kind` | query | no | string | Filter by vocabulary kind. | | `search` | query | no | string | Case-insensitive substring match on the entry name (value is trimmed; blank values ignored). | | `limit` | query | no | integer | Maximum number of entries to return. | ## Responses - **200** — Active vocabulary entries matching the filters, ordered by kind then name ascending. → [MaterialVocabularyListResponse](/schemas/MaterialVocabularyListResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/materials' ``` ## See also Schemas: [MaterialVocabularyListResponse](/schemas/MaterialVocabularyListResponse.md). ================================================================================ # FILE: /okf/operations/registerTraceabilityEvent.md ================================================================================ --- type: API Endpoint title: Register a UNTP/EPCIS 2.0 traceability event (VC-shaped) description: Registers a supply-chain traceability event carried as a VC-shaped UNTP credential and persists it as an EPCIS 2.0 event row scoped to your tenant. resource: https://opendpp-node.eu/api/v1/events tags: - POST - traceability-audit generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/events` **Domain:** [Traceability & Audit](/tags/traceability-audit.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Registers a supply-chain traceability event carried as a VC-shaped UNTP credential and persists it as an EPCIS 2.0 event row scoped to your tenant. **Permission:** `passport:update` (write operation — subscription gating applies, see 402). When the node operator enforces MFA, writes from user-backed sessions (cookie or Bearer JWT) whose MFA policy requires a second factor (user policy `REQUIRED`, or `DEFAULT` with the workspace's MFA-by-default setting, which is on by default) receive 403 without one; API-key clients are exempt. Cookie-session clients must send the `X-CSRF-Token` header (double-submit with the `opendpp_csrf` cookie); Bearer JWT / API-key clients are exempt. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. **Validation pipeline (in order):** 1. *Structural* — the body must be an object containing `credentialSubject`, otherwise 400 `Bad Request`. 2. *EPCIS rule* — `action` is strictly forbidden on `TransformationEvent` (any non-null value → 400 `Schema Validation Error`). 3. *Cryptographic* — the credential's `proof` MUST be a conformant W3C `DataIntegrityProof` with `cryptosuite: "ecdsa-jcs-2019"` and a multibase base58btc (`z…`) `proofValue`; any other proof shape (e.g. the legacy key-sorted `MerkleTreeAttestationProof`) is rejected. The ECDSA P-256 signature is verified per that cryptosuite over `sha256(JCS(proof options)) ‖ sha256(JCS(credential without proof))` — RFC 8785 JCS canonicalization, IEEE-P1363 raw r‖s — a conformant, interoperable Data Integrity suite, which is what makes the persisted `isUntpCompliant: true` honest. The verification key is resolved in trust order: (a) an embedded `proof.verificationMethod.x5c` chain, accepted ONLY when the node has trust anchors configured, the chain validates against them, every certificate is currently valid, and the leaf attests the issuer; (b) ALL of the authoritative vault keys (current + retired, so a pre-rotation credential still verifies) of the tenant whose UNIQUE subdomain EXACTLY equals the trailing `:`-segment of the issuer DID. If no key resolves or the signature does not verify → 400 `Cryptographic Verification Failed`. 4. *Operator scoping* — if your API key is scoped to an Economic Operator, the credential's declared operator DID — the `issuer` DID, or `credentialSubject.responsibleOperatorDid` only when `issuer` is absent — must contain the bound operator's registration id (e.g. `EU-DEFAULT-001`), otherwise 403 with `message: "Your access is restricted to Economic Operator: ()"`. **Persistence:** the stored event id is ALWAYS server-generated (UUID) — the credential's own `id` is never used as the primary key (prevents cross-tenant id squatting); the issuer DID is retained as `issuerDid`. Defaults applied on write: `bizStep` → `urn:epcglobal:cbv:bizstep:receiving`; `disposition` → `urn:epcglobal:cbv:disp:in_progress`; `readPoint` → `geo:,` derived from `credentialSubject.originLocation` when present; `bizLocation` → `responsibleOperatorDid`; `eventTime` → `issuanceDate`, else the server clock; `epcList` → `[credentialSubject.id]` when not supplied as an array (or `[]`). The row is stored with `isUntpCompliant: true` and the `proof.proofValue` retained. **Caveats:** `credentialSubject.eventType` must be one of the documented event-type values and `action` (when present) one of `ADD`/`OBSERVE`/`DELETE` — both map to server-side enums, and a missing or unknown value is only rejected at the persistence layer and surfaces as the 500 `Database Persistence Failed` body, not as a 400. Note the 201 envelope is `{status: "success", ...}`, NOT the usual `{success: true, ...}` shape. This endpoint does not create lineage edges between events; the lineage DAG read by `GET /api/v1/events/{id}/lineage` is built from lineage relations maintained separately on the node. ## Request body Schema (required): [UntpEventCredential](/schemas/UntpEventCredential.md). ```json { "@context": [ "https://www.w3.org/ns/credentials/v2", "https://vocabulary.uncefact.org/untp/dpp/" ], "id": "urn:uuid:0e7a2c1c-6f4e-4a08-9d2e-3b1f5a7c9d10", "type": [ "VerifiableCredential", "DigitalTraceabilityEvent" ], "issuer": "did:web:opendpp-node.eu:EU-DEFAULT-001:demo", "issuanceDate": "2026-06-12T09:41:00.000Z", "credentialSubject": { "id": "urn:epc:id:sgtin:0950110153.0003.SN-2026-000123", "eventType": "ObjectEvent", "action": "OBSERVE", "bizStep": "urn:epcglobal:cbv:bizstep:shipping", "disposition": "urn:epcglobal:cbv:disp:in_transit", "readPoint": "geo:41.1496,-8.6109", "bizLocation": "urn:epc:id:sgln:0950110153000..0", "eventTime": "2026-06-12T08:30:00.000Z", "epcList": [ "urn:epc:id:sgtin:0950110153.0003.SN-2026-000123" ], "responsibleOperatorDid": "did:web:opendpp-node.eu:EU-DEFAULT-001:demo" }, "proof": { "type": "DataIntegrityProof", "cryptosuite": "ecdsa-jcs-2019", "created": "2026-06-12T09:41:00.000Z", "proofPurpose": "assertionMethod", "verificationMethod": "did:web:opendpp-node.eu:EU-DEFAULT-001:demo#key-1", "proofValue": "z4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xEQLExampleEcdsaJcs2019MultibaseBase58btcProofValue" } } ``` ## Responses - **201** — Event registered. → [TraceEventRegistered](/schemas/TraceEventRegistered.md) - **400** — Route-specific validation failure, always {success: false, error, message} with one of three error values: Bad Request (body missing or no credentialSubject),… → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Persistence failure — also returned when credentialSubject.eventType/action is missing or not a valid enum value (the server-side enum rejects the row). → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/events' \ --data '{"@context":["https://www.w3.org/ns/credentials/v2","https://vocabulary.uncefact.org/untp/dpp/"],"id":"urn:uuid:0e7a2c1c-6f4e-4a08-9d2e-3b1f5a7c9d10","type":["VerifiableCredential","DigitalTraceabilityEvent"],"issuer":"did:web:opendpp-node.eu:EU-DEFAULT-001:demo","issuanceDate":"2026-06-12T09:41:00.000Z","credentialSubject":{"id":"urn:epc:id:sgtin:0950110153.0003.SN-2026-000123","eventType":"ObjectEvent","action":"OBSERVE","bizStep":"urn:epcglobal:cbv:bizstep:shipping","disposition":"urn:epcglobal:cbv:disp:in_transit","readPoint":"geo:41.1496,-8.6109","bizLocation":"urn:epc:id:sgln:09501101530…' ``` ## See also Schemas: [Error](/schemas/Error.md), [TraceEventRegistered](/schemas/TraceEventRegistered.md), [UntpEventCredential](/schemas/UntpEventCredential.md). ================================================================================ # FILE: /okf/operations/captureEpcisDocument.md ================================================================================ --- type: API Endpoint title: Capture a native GS1 EPCIS 2.0 document (JSON/JSON-LD) description: Captures a native GS1 EPCIS 2.0 document — the standard's own JSON/JSON-LD interchange format — and persists each supported event as an EPCIS event row scoped to your tenant, alongside the VC-shaped POST /api/v1/events path. resource: https://opendpp-node.eu/api/v1/events/epcis tags: - POST - traceability-audit generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/events/epcis` **Domain:** [Traceability & Audit](/tags/traceability-audit.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Captures a native **GS1 EPCIS 2.0 document** — the standard's own JSON/JSON-LD interchange format — and persists each supported event as an EPCIS event row scoped to your tenant, alongside the VC-shaped `POST /api/v1/events` path. Send the document exactly as your EPCIS infrastructure produces it. **Permission:** `passport:update` (write operation — subscription gating applies, see 402). When the node operator enforces MFA, writes from user-backed sessions (cookie or Bearer JWT) whose MFA policy requires a second factor (user policy `REQUIRED`, or `DEFAULT` with the workspace's MFA-by-default setting, which is on by default) receive 403 without one; API-key clients are exempt. Cookie-session clients must send the `X-CSRF-Token` header (double-submit with the `opendpp_csrf` cookie); Bearer JWT / API-key clients are exempt. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. **Validation:** the WHOLE document is validated against the official GS1 EPCIS **2.0.1** JSON Schema (vendored and pinned on the node) before any event is stored — a non-conformant document is rejected 400 with the first few schema violations under `errors[]`. Notable rules the OFFICIAL schema enforces: `@context` and `creationDate` are required; `bizStep`/`disposition` must use the CBV **short names** (e.g. `commissioning`, `in_transit`) or a custom (non-CBV) URI — the legacy `urn:epcglobal:cbv:*` URN form is REJECTED by the standard's schema; `action` is forbidden on `TransformationEvent`; `readPoint`/`bizLocation` carry `{id: }`. Only `type: "EPCISDocument"` is accepted (no `EPCISQueryDocument`, no bare events), and `epcisBody.eventList` must be non-empty. **Per-event capture (partial success):** events are processed independently and the 201 response reports `results[]` (captured) and `errors[]` (rejected) by `index`. An event is rejected — never silently dropped — when its type is outside this node's traceability model (`ObjectEvent`, `AggregationEvent`, `TransformationEvent`, `AssociationEvent` are supported; `TransactionEvent` is not) or when it identifies stock ONLY by quantity lists (no `epcList`/`parentID`/`childEPCs`/`inputEPCList`/`outputEPCList` — nothing EPC-identified would remain to trace). If EVERY event is rejected the response is 400 `No Events Captured` with the same `errors[]`. **Fidelity disclosure:** recognized EPCIS fields the node does not persist (`eventID`, quantity lists, `sensorElementList`, `bizTransactionList`, `sourceList`/`destinationList`, `persistentDisposition`, `errorDeclaration`, `ilmd`, custom extension fields, …) are listed per event under `results[].ignoredFields` instead of being silently discarded. **Persistence:** row ids are ALWAYS server-generated (UUID) — a client-supplied `eventID` is never adopted as the primary key (it is disclosed under `ignoredFields`); CBV short names are normalized to the node's stored URN form (`urn:epcglobal:cbv:bizstep:*` / `urn:epcglobal:cbv:disp:*`, the same form the VC-shaped path stores and the lineage projection reads); defaults when absent: `bizStep` → `receiving`, `disposition` → `in_progress`. Rows captured on this path carry **no per-event credential** and are stored with `isUntpCompliant: false` (API-key provenance only) — they are never presented as UNTP-verified. This endpoint does not create lineage edges between events. ## Request body Schema (required): [EpcisDocument](/schemas/EpcisDocument.md). ```json { "@context": [ "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld" ], "type": "EPCISDocument", "schemaVersion": "2.0", "creationDate": "2026-07-02T10:00:00.000Z", "epcisBody": { "eventList": [ { "type": "ObjectEvent", "action": "ADD", "bizStep": "commissioning", "disposition": "active", "eventTime": "2026-01-15T08:00:00.000Z", "eventTimeZoneOffset": "+00:00", "epcList": [ "urn:epc:id:sgtin:0950110.154904.1" ], "readPoint": { "id": "geo:41.1579,-8.6291" }, "bizLocation": { "id": "urn:opendpp:location:PT-SAMPLE-SITE-3" } }, { "type": "TransformationEvent", "bizStep": "commissioning", "disposition": "in_progress", "eventTime": "2026-01-16T08:00:00.000Z", "eventTimeZoneOffset": "+00:00", "inputEPCList": [ "urn:epc:id:sgtin:0950110.154904.1" ], "outputEPCList": [ "urn:epc:id:sgtin:0950110.154100.1" ], "readPoint": { "id": "geo:41.1579,-8.6291" } } ] } } ``` ## Responses - **201** — At least one event captured. → [EpcisCaptureResponse](/schemas/EpcisCaptureResponse.md) - **400** — Always {success: false, error, message} (plus errors[] detail where noted) with one of: EPCIS Schema Validation Failed (the document does not conform to the of… → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/events/epcis' \ --data '{"@context":["https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld"],"type":"EPCISDocument","schemaVersion":"2.0","creationDate":"2026-07-02T10:00:00.000Z","epcisBody":{"eventList":[{"type":"ObjectEvent","action":"ADD","bizStep":"commissioning","disposition":"active","eventTime":"2026-01-15T08:00:00.000Z","eventTimeZoneOffset":"+00:00","epcList":["urn:epc:id:sgtin:0950110.154904.1"],"readPoint":{"id":"geo:41.1579,-8.6291"},"bizLocation":{"id":"urn:opendpp:location:PT-SAMPLE-SITE-3"}},{"type":"TransformationEvent","bizStep":"commissioning","disposition":"in_progress","eventTime":"2026…' ``` ## See also Schemas: [EpcisCaptureResponse](/schemas/EpcisCaptureResponse.md), [EpcisDocument](/schemas/EpcisDocument.md), [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/getEventLineage.md ================================================================================ --- type: API Endpoint title: Retrieve the upstream pedigree of an event as a recursive lineage DAG description: "Returns the full upstream pedigree of a traceability event as a recursive Directed Acyclic Graph: the root event plus, in parents, every event linked upstream through lineage relations registered on the node, walked transitively (parents o…" resource: https://opendpp-node.eu/api/v1/events/{id}/lineage tags: - GET - traceability-audit generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/events/{id}/lineage` **Domain:** [Traceability & Audit](/tags/traceability-audit.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Returns the full upstream pedigree of a traceability event as a recursive Directed Acyclic Graph: the root event plus, in `parents`, every event linked upstream through lineage relations registered on the node, walked transitively (parents of parents). A shared ancestor reached through multiple downstream paths is repeated under EACH path — the DAG is expanded into a tree in the response, not deduplicated; only a true cycle aborts the walk (400). **Permission:** `passport:read`. Every node in the walk — the root AND each upstream parent — is scoped to the caller's tenant; an event belonging to another tenant is invisible and the request fails with 404 (no cross-tenant pedigree reads). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. **Caveats:** if the lineage graph contains a circular reference the walk aborts with 400. Any other failure (unknown id, other-tenant id, missing parent) is reported as the same deliberately generic 404 body. `eventTime` is serialized as ISO 8601 UTC; `epcs` is parsed from the stored EPC list (a non-array value degrades to `[]`); `location` mirrors the stored `bizLocation`. **Content negotiation (EPCIS projection):** `Accept: application/ld+json` returns the SAME tenant-scoped lineage as a native **GS1 EPCIS 2.0 document** (`EPCISDocument` with the walk's events under `epcisBody.eventList`, ordered by `eventTime`, bounded to 500 events) instead of the recursive JSON tree — another projection of the same canonical rows, mirroring the AAS/VC Accept-header pattern on the passport resolution routes. Emitted documents use the official CBV short names (stored `urn:epcglobal:cbv:*` values are mapped back), expose row ids as `eventID` URNs (`urn:uuid:*`, or `urn:opendpp:event:*` for non-UUID ids), and wrap non-URI stored locations as `urn:opendpp:location:*`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | EPCIS event id — the server-generated UUID returned as eventId by POST /api/v1/events. | ## Responses - **200** — The lineage DAG rooted at the requested event. → [EpcisDocument](/schemas/EpcisDocument.md), [TraceLineageResponse](/schemas/TraceLineageResponse.md) - **400** — Circular reference detected while walking the lineage graph. → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The event does not exist, belongs to another tenant, or an upstream node could not be retrieved. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/events/{id}/lineage' ``` ## See also Schemas: [EpcisDocument](/schemas/EpcisDocument.md), [Error](/schemas/Error.md), [TraceLineageResponse](/schemas/TraceLineageResponse.md). ================================================================================ # FILE: /okf/operations/verifyPassportSeal.md ================================================================================ --- type: API Endpoint title: Publicly verify a passport's seal, certificate chain and timestamp description: Public seal-verification API — cryptographically verifies that a Digital Product Passport document was sealed by an economic-operator tenant registered on this node and has not been tampered with. resource: https://opendpp-node.eu/api/v1/audit/verify tags: - POST - traceability-audit generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/audit/verify` **Domain:** [Traceability & Audit](/tags/traceability-audit.md) **Authentication:** **Public** — no authentication required. **Public seal-verification API** — cryptographically verifies that a Digital Product Passport document was sealed by an economic-operator tenant registered on this node and has not been tampered with. No authentication required. **Rate limit:** **30 requests/min per IP**. This bucket emits no rate-limit headers of its own — any `x-ratelimit-*` headers on responses (including this 429) come from the global 100 req/min limiter and describe that budget, not the 30/min one. The 429 body is the two-field `{"error": "Too Many Requests", "message": "Rate limit exceeded."}`. **Input resolution.** `payload` is required. `signature` and `publicKey` may be supplied top-level, or are extracted from the document's embedded proof block: `signature` ← `payload.proof.proofValue` (else `payload.proof.signatureValue`); `publicKey` ← `payload.proof.publicKeyPem`, else the leaf certificate's SPKI when `payload.proof.x5c` is present. If, after extraction, any of the three is still missing → 400. The public key is CRLF-normalized and trimmed before matching. **Verification pipeline (in order):** 1. **Certificate-chain report (optional).** If `payload.proof.x5c` is a non-empty array of base64-DER certificates (leaf first), the chain is parsed and a `certificate` report is built: the leaf's `subject` / `issuer` / `validFrom` / `validTo` (X.509 textual dates such as `Jan 10 00:00:00 2026 GMT` — NOT ISO 8601), `chainValid` (every link signature-verifies against the next certificate, every certificate is inside its validity window, and the top of the chain is anchored to this node's seal CA — SHA-256 fingerprint match or signature under the CA key; the CA is published at `GET /.well-known/opendpp-seal-ca.pem`), and `keyMatchesProof` (the leaf SPKI equals the supplied `publicKey`, whitespace-insensitive; always `true` when no explicit key was supplied). An unparseable chain yields `{"chainValid": false, "error": "Unparseable x5c certificate chain"}` and does NOT fail the request. This reports the CERTIFIED identity of the seal creator. SECURITY: the report is attached ONLY on a `verified: true` outcome whose chain is TRUSTED (`chainValid` AND `keyMatchesProof` both true) — an untrusted/self-signed chain, one outside its validity window or not anchored to this node's seal CA, or one whose leaf key does not match the verifying key, is never surfaced as a `certificate` block (it must not present an unverified identity as authoritative). The two policy-failure responses omit it too. 2. **Key-registration gate.** The `publicKey` must exactly match the registered signing public key of a tenant on this node (trailing-newline tolerant) — otherwise HTTP **200** with `verified: false` and an explanatory `message`. Verification-policy failures are reported in-band, never as HTTP errors. 3. **Operator-binding gate (fail-closed).** If the payload declares an operator registration id (`payload.operator.regId`, else `payload.economicOperator.regId`), that id MUST resolve to an Economic Operator registered on this node AND that operator MUST be bound to the signing tenant (a workspace–operator binding registered on this node). A declared operator that is unregistered, or registered but not bound to the key-owning tenant, → 200 `verified: false` with an explanatory `message`. Payloads that declare no operator id skip this gate. 4. **Signature verification (two phases).** *Phase 1 — Merkle seal:* when `payload.metadata` is an object (or, when the `metadata` key is entirely absent, the whole `payload` is treated as the metadata), the SHA-256 Merkle tree over the metadata's top-level properties is rebuilt and the base64 ECDSA (P-256 / SHA-256) `signature` is verified against the recomputed root. Every leaf is recomputed from the actual values — caller-supplied redacted-leaf hashes are NOT accepted (they would let a tampered field be smuggled past verification), so a publicly redacted document will not pass the Merkle phase: verify the unredacted, privileged document. *Phase 2 — fallback:* if the Merkle phase does not verify, the signature is verified over the deterministic key-sorted canonicalization of the entire `payload`. 5. **RFC 3161 timestamp report (optional).** When `payload.proof.rfc3161.token` is a non-empty base64-DER TimeStampToken, the response includes `timestamp` with the TSA-asserted `genTime` parsed from the token's TSTInfo (or `genTime: null` plus a `note` when the token cannot be parsed). When the node has a TSA trust anchor configured, the report also carries `timeAuthenticated` — the node's own verification of the token's CMS SignedData signature over its TSTInfo PLUS full RFC 3161 trust-path validation of the signer to that anchor (a critical `id-kp-timeStamping` EKU, validity at the asserted `genTime`, CA-constrained intermediates) (`false`, and the asserted time unauthenticated, when no CA is configured, the signature fails, or the path is not policy-valid); a verifier may still run its own `openssl ts -verify`. Like `certificate`, it appears only on the final verification outcome. **Outcome.** A processed verification ALWAYS returns HTTP 200 with `verified: true|false`; 400 is reserved for missing parameters or an exception thrown while verifying (e.g. an undecodable public key). `timestamp` is attached only when verification proceeds past the key-registration and operator-binding gates; `certificate` is attached only on a `verified: true` outcome whose chain is trusted (`chainValid` AND `keyMatchesProof`) — the two policy `verified: false` responses (and any untrusted-chain outcome) omit `certificate`, even when an x5c chain and/or an RFC 3161 token were supplied. The 400 bodies on this public endpoint are `{"success": false, "message": "..."}` — they include `success` but OMIT the `error` field. (A syntactically malformed JSON body is rejected earlier by the framework with its default `{statusCode, error, message}` body; a POST with no body at all — no `Content-Type` — fails before processing with a framework-default 500, so send at least `{}`. An empty `application/json` body is treated as `{}` and yields the documented 400.) ## Request body Schema (required): [SealVerifyRequest](/schemas/SealVerifyRequest.md). ```json { "payload": { "passportId": "9b2fa884-5b1d-4c0e-9a3f-2d7c8e1f6a45", "productId": "09501101530003", "operator": { "name": "OpenDPP Demo Eco Industries", "regId": "EU-DEFAULT-001" }, "metadata": { "category": "textiles", "originCountry": "PT", "materialComposition": [ { "material": "Organic Cotton", "percentage": 80 }, { "material": "Recycled Polyester", "percentage": 20 } ] }, "proof": { "type": "DataIntegrityProof", "proofValue": "MEQCIB3pZ8sVxampleMerkleRootSealSignatureFirstIntegerAiAW6kQexampleSecondDerIntegerValue0123456789abcd==", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleDemoTenantSealPublicKey\n0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNO=\n-----END PUBLIC KEY-----", "x5c": [ "MIIB2zCCAYGgAwIBAgIUExampleLeafSealCertificateBase64Der", "MIIB4TCCAYagAwIBAgIUExampleNodeSealCaCertificateBase64Der" ], "rfc3161": { "token": "MIIKlAYJKoZIhvcNAQcCoIIKhTCCCoECAQMxDzANBglghkgBZQMEAgEFADCBExampleTimeStampTokenDer" } } } } ``` ## Responses - **200** — Verification processed. → [SealVerifyResponse](/schemas/SealVerifyResponse.md) - **400** — Missing cryptographic parameters (after proof-block extraction), or an exception during verification (e.g. undecodable key material). - **429** — Public-resolution rate limit exceeded (30 requests/min per IP; no rate-limit headers). → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/audit/verify' \ --data '{"payload":{"passportId":"9b2fa884-5b1d-4c0e-9a3f-2d7c8e1f6a45","productId":"09501101530003","operator":{"name":"OpenDPP Demo Eco Industries","regId":"EU-DEFAULT-001"},"metadata":{"category":"textiles","originCountry":"PT","materialComposition":[{"material":"Organic Cotton","percentage":80},{"material":"Recycled Polyester","percentage":20}]},"proof":{"type":"DataIntegrityProof","proofValue":"MEQCIB3pZ8sVxampleMerkleRootSealSignatureFirstIntegerAiAW6kQexampleSecondDerIntegerValue0123456789abcd==","publicKeyPem":"-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleDemoTenantSe…' ``` ## See also Schemas: [SealVerifyRequest](/schemas/SealVerifyRequest.md), [SealVerifyResponse](/schemas/SealVerifyResponse.md). ================================================================================ # FILE: /okf/operations/getTenantDidDocument.md ================================================================================ --- type: API Endpoint title: Resolve a tenant's did:web DID document description: Resolves the issuing workspace's did:web DID document (application/did+json). resource: https://opendpp-node.eu/tenants/{tenantId}/did.json tags: - GET - verifiable-credentials generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /tenants/{tenantId}/did.json` **Domain:** [Verifiable Credentials](/tags/verifiable-credentials.md) **Authentication:** **Public** — no authentication required. Resolves the issuing workspace's `did:web` DID document (`application/did+json`). The DID is `did:web:opendpp-node.eu:tenants:{tenantId}`, which per the did:web method dereferences here. The document exposes **only public key material** — the workspace's signing public key(s) as `JsonWebKey2020` verification methods, each with a stable `#key-` id matching the `kid` of the credentials it signs. Use it to verify any OpenDPP-issued Verifiable Credential (`Accept: application/vc+jwt`, `application/vc+ld+json`, or `application/dc+sd-jwt` on the public resolution endpoints) without out-of-band key exchange. Both current and retired keys are published and listed in `assertionMethod`/`authentication`, so credentials issued before a key rotation still verify; new credentials always use the current key. The optional `name` is the issuer's authoritative legal name (the same value used in every credential's `issuer.name`). No authentication, no permission (public endpoint). Subject only to the global platform rate limit (100 req/min/IP). A workspace that has never provisioned a signing key returns 404. Never returns private key material. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `tenantId` | path | yes | string | The issuing workspace (tenant) id — the {tenantId} of its did:web:opendpp-node.eu:tenants:{tenantId} DID. | ## Responses - **200** — The tenant's did:web DID document (public keys only). → [DidWebDocument](/schemas/DidWebDocument.md) - **404** — No DID document for this tenant (the workspace has not provisioned a signing key). → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. ## Example ```bash curl -s \ -X GET 'https://opendpp-node.eu/tenants/{tenantId}/did.json' ``` ## See also Schemas: [DidWebDocument](/schemas/DidWebDocument.md), [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/getTenantRevocationStatusList.md ================================================================================ --- type: API Endpoint title: Tenant revocation status list (W3C Bitstring Status List) description: Serves the workspace's W3C Bitstring Status List as a signed enveloping vc+jwt (application/vc+jwt) — a BitstringStatusListCredential whose GZIP+base64 encoded bitstring sets the bit of every passport whose status is RECALLED or DECOMMISSI… resource: https://opendpp-node.eu/tenants/{tenantId}/status/revocation tags: - GET - verifiable-credentials generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /tenants/{tenantId}/status/revocation` **Domain:** [Verifiable Credentials](/tags/verifiable-credentials.md) **Authentication:** **Public** — no authentication required. Serves the workspace's W3C **Bitstring Status List** as a signed enveloping `vc+jwt` (`application/vc+jwt`) — a `BitstringStatusListCredential` whose GZIP+base64 encoded bitstring sets the bit of every passport whose status is RECALLED or DECOMMISSIONED. An OpenDPP-issued DPP credential's `credentialStatus.statusListCredential` points here; a verifier fetches this list and checks the bit at the credential's `statusListIndex` to determine whether it has been revoked. Signed by the workspace's current key (stable `kid`), verifiable via the DID document at `/tenants/{tenantId}/did.json`. No authentication, no permission (public endpoint). Subject only to the global platform rate limit (100 req/min/IP). A workspace with no signing key returns 404. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `tenantId` | path | yes | string | The issuing workspace (tenant) id. | ## Responses - **200** — The signed BitstringStatusListCredential as a compact vc+jwt (JWS string). - **404** — No status list for this tenant (unknown workspace or no signing key). → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. ## Example ```bash curl -s \ -X GET 'https://opendpp-node.eu/tenants/{tenantId}/status/revocation' ``` ## See also Schemas: [Error](/schemas/Error.md). ================================================================================ # FILE: /okf/operations/listWebhookSubscriptions.md ================================================================================ --- type: API Endpoint title: List webhook subscriptions (signing secrets stripped) description: Lists all webhook subscriptions of the calling workspace. resource: https://opendpp-node.eu/api/v1/webhooks/subscriptions tags: - GET - webhooks generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/webhooks/subscriptions` **Domain:** [Webhooks](/tags/webhooks.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Lists all webhook subscriptions of the calling workspace. Unpaginated (the per-workspace cap is 25). **Permission:** `webhook:read` (read permissions are not subscription-gated, so no `402`). The HMAC signing `secret` is **stripped from every row** — it is returned once by the create endpoint and once by `rotate-secret`. `isActive` reflects whether the subscription receives deliveries; toggle it with `PATCH /api/v1/webhooks/subscriptions/{id}`. Global rate limit 100 requests/min/IP. ## Responses - **200** — All subscriptions of the workspace, secrets removed. → [WebhookSubscriptionListResponse](/schemas/WebhookSubscriptionListResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/webhooks/subscriptions' ``` ## See also Schemas: [Error](/schemas/Error.md), [WebhookSubscriptionListResponse](/schemas/WebhookSubscriptionListResponse.md). ================================================================================ # FILE: /okf/operations/createWebhookSubscription.md ================================================================================ --- type: API Endpoint title: Register a webhook subscription (signing secret returned once) description: Registers an endpoint to receive passport lifecycle webhooks for the calling workspace. resource: https://opendpp-node.eu/api/v1/webhooks/subscriptions tags: - POST - webhooks generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/webhooks/subscriptions` **Domain:** [Webhooks](/tags/webhooks.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Registers an endpoint to receive passport lifecycle webhooks for the calling workspace. **Permission:** `webhook:write`. Cookie-session callers must send the `X-CSRF-Token` header (double-submit); Bearer API-key/JWT clients are exempt. Write permissions are additionally gated on an active workspace subscription (`402`). **URL validation (SSRF guard):** `url` must be an absolute `http(s)` URL. At registration the hostname is DNS-resolved and the request is rejected with `400` if any resolved A/AAAA record is loopback, RFC 1918/CGNAT private, link-local / cloud-metadata (`169.254.0.0/16`), multicast, or an equivalent IPv6 range. At delivery time the socket is pinned to the validated IP and redirects are never followed. **Event filters:** `events` must be a non-empty array drawn from `passport.ingested`, `passport.updated`, `passport.sealed`, `passport.recalled`, `passport.status_updated`, `*`. The `*` wildcard matches every emitted event. **Signing secret — shown once:** the `201` response contains the full subscription row **including** the HMAC-SHA256 signing secret (`whsec_` + 32 lowercase hex chars, server-generated, never client-supplied). This is the only time the secret is ever returned: the list endpoint strips it and there is no rotation or update endpoint — delete and re-create to rotate. **Limits:** maximum **25 subscriptions per workspace** (`409 Conflict`). Global rate limit 100 requests/min/IP (`429` with `x-ratelimit-*` headers). Unknown request-body fields are ignored. ## Request body Schema (required): [WebhookSubscriptionCreateRequest](/schemas/WebhookSubscriptionCreateRequest.md). ```json { "url": "https://erp.example.com/hooks/opendpp", "events": [ "passport.ingested", "passport.sealed" ] } ``` ## Responses - **201** — Subscription registered. → [WebhookSubscriptionCreateResponse](/schemas/WebhookSubscriptionCreateResponse.md) - **400** — Validation failure. → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **409** — The workspace already has 25 webhook subscriptions (the per-tenant cap). → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Persistence failed (details logged server-side) — message "Failed to register webhook subscription.". → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X POST 'https://opendpp-node.eu/api/v1/webhooks/subscriptions' \ --data '{"url":"https://erp.example.com/hooks/opendpp","events":["passport.ingested","passport.sealed"]}' ``` ## See also Schemas: [Error](/schemas/Error.md), [WebhookSubscriptionCreateRequest](/schemas/WebhookSubscriptionCreateRequest.md), [WebhookSubscriptionCreateResponse](/schemas/WebhookSubscriptionCreateResponse.md). ================================================================================ # FILE: /okf/operations/updateWebhookSubscription.md ================================================================================ --- type: API Endpoint title: Update a webhook subscription (url / events / active) description: "Partially updates a subscription: any of url, events, isActive (key present = set, omitted = unchanged)." resource: https://opendpp-node.eu/api/v1/webhooks/subscriptions/{id} tags: - PATCH - webhooks generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `PATCH /api/v1/webhooks/subscriptions/{id}` **Domain:** [Webhooks](/tags/webhooks.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Partially updates a subscription: any of `url`, `events`, `isActive` (key present = set, omitted = unchanged). A new `url` is re-validated by the DNS-resolving SSRF guard (same rules as creation); `events` must be a non-empty subset of the allowed filters. The signing `secret` is **not** editable here — use `rotate-secret`. An empty body returns the current subscription unchanged. The response **strips the secret**. **Permission:** `webhook:write`. Cookie sessions must send `X-CSRF-Token`; write permissions are subscription-gated (**402** when lapsed). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Webhook subscription UUID (as returned at creation / by the list endpoint). | ## Request body Schema: [WebhookSubscriptionUpdateRequest](/schemas/WebhookSubscriptionUpdateRequest.md). ```json { "events": [ "passport.sealed", "passport.recalled" ], "isActive": false } ``` ## Responses - **200** — Updated subscription (secret stripped). → [WebhookSubscriptionUpdateResponse](/schemas/WebhookSubscriptionUpdateResponse.md) - **400** — Invalid url (not a string / SSRF-rejected), empty/invalid events, or non-boolean isActive. → [Error](/schemas/Error.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -H 'Content-Type: application/json' \ -X PATCH 'https://opendpp-node.eu/api/v1/webhooks/subscriptions/{id}' \ --data '{"events":["passport.sealed","passport.recalled"],"isActive":false}' ``` ## See also Schemas: [Error](/schemas/Error.md), [WebhookSubscriptionUpdateRequest](/schemas/WebhookSubscriptionUpdateRequest.md), [WebhookSubscriptionUpdateResponse](/schemas/WebhookSubscriptionUpdateResponse.md). ================================================================================ # FILE: /okf/operations/deleteWebhookSubscription.md ================================================================================ --- type: API Endpoint title: Delete a webhook subscription description: Deletes a webhook subscription, stopping future deliveries to its endpoint. resource: https://opendpp-node.eu/api/v1/webhooks/subscriptions/{id} tags: - DELETE - webhooks generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `DELETE /api/v1/webhooks/subscriptions/{id}` **Domain:** [Webhooks](/tags/webhooks.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Deletes a webhook subscription, stopping future deliveries to its endpoint. **Permission:** `webhook:write` (cookie sessions must send `X-CSRF-Token`; write permissions are subscription-gated, `402`). The lookup is tenant-scoped: an `id` that exists but belongs to another workspace returns the same `404` with message `"Webhook subscription not found under your tenant"`. Deleting and re-creating is the only way to rotate a signing secret. Global rate limit 100 requests/min/IP. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Webhook subscription UUID (as returned at creation / by the list endpoint). | ## Responses - **200** — Subscription deleted. → [WebhookSubscriptionDeleteResponse](/schemas/WebhookSubscriptionDeleteResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X DELETE 'https://opendpp-node.eu/api/v1/webhooks/subscriptions/{id}' ``` ## See also Schemas: [Error](/schemas/Error.md), [WebhookSubscriptionDeleteResponse](/schemas/WebhookSubscriptionDeleteResponse.md). ================================================================================ # FILE: /okf/operations/rotateWebhookSecret.md ================================================================================ --- type: API Endpoint title: Rotate a webhook subscription's signing secret description: Mints a fresh HMAC-SHA256 signing secret for the subscription and returns it once (the old secret stops validating immediately). resource: https://opendpp-node.eu/api/v1/webhooks/subscriptions/{id}/rotate-secret tags: - POST - webhooks generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/webhooks/subscriptions/{id}/rotate-secret` **Domain:** [Webhooks](/tags/webhooks.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Mints a fresh HMAC-SHA256 signing secret for the subscription and returns it **once** (the old secret stops validating immediately). Use this after a suspected secret leak, or on a rotation schedule. There is no request body. Update your receiver to verify signatures with the new secret as soon as you rotate — deliveries in flight use whichever secret was current when signed. **Permission:** `webhook:write`. Cookie sessions must send `X-CSRF-Token`; write permissions are subscription-gated (**402** when lapsed). **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Webhook subscription UUID (as returned at creation / by the list endpoint). | ## Responses - **200** — Rotated. → [WebhookSecretRotateResponse](/schemas/WebhookSecretRotateResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X POST 'https://opendpp-node.eu/api/v1/webhooks/subscriptions/{id}/rotate-secret' ``` ## See also Schemas: [WebhookSecretRotateResponse](/schemas/WebhookSecretRotateResponse.md). ================================================================================ # FILE: /okf/operations/listWebhookDeliveries.md ================================================================================ --- type: API Endpoint title: List recent webhook delivery attempts (the outbox) description: Returns recent delivery records (the outbox), newest first, for debugging endpoint failures. resource: https://opendpp-node.eu/api/v1/webhooks/deliveries tags: - GET - webhooks generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `GET /api/v1/webhooks/deliveries` **Domain:** [Webhooks](/tags/webhooks.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Returns recent delivery records (the outbox), newest first, for debugging endpoint failures. Records are **event-level** (one per emitted event, fanned out to all matching subscriptions), not per-subscription — `status` reflects the event's overall delivery state and `errorMessage` joins per-endpoint errors. Payloads are **not** included. Filter with `?status=PENDING|DELIVERED|FAILED` and cap with `?limit=` (1–200, default 50; a non-numeric value falls back to the default). **Permission:** `webhook:read`. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `status` | query | no | string | Filter by delivery state. | | `limit` | query | no | integer | Max records to return. | ## Responses - **200** — Recent delivery records, newest first. → [WebhookDeliveriesResponse](/schemas/WebhookDeliveriesResponse.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X GET 'https://opendpp-node.eu/api/v1/webhooks/deliveries' ``` ## See also Schemas: [WebhookDeliveriesResponse](/schemas/WebhookDeliveriesResponse.md). ================================================================================ # FILE: /okf/operations/testWebhookSubscription.md ================================================================================ --- type: API Endpoint title: Send a signed test event to a subscription description: Delivers a single signed sample event to the subscription's URL right now and reports the outcome — use it to confirm your endpoint is reachable and that your signature verification works, without waiting for a real passport event. resource: https://opendpp-node.eu/api/v1/webhooks/subscriptions/{id}/test tags: - POST - webhooks generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- `POST /api/v1/webhooks/subscriptions/{id}/test` **Domain:** [Webhooks](/tags/webhooks.md) **Authentication:** **API key required** — `Authorization: Bearer op_dpp_token_…`. Delivers a single **signed sample** event to the subscription's URL right now and reports the outcome — use it to confirm your endpoint is reachable and that your signature verification works, without waiting for a real passport event. The payload is a representative public JSON-LD passport document marked `_test: true`; it is signed exactly like a production delivery (HMAC-SHA256 over `${timestamp}.${body}`). The event type is a concrete value from the subscription's filter (the `*` wildcard is skipped; defaults to `passport.sealed`). **Permission:** `webhook:write`. **Rate limit:** your plan's per-key budget applies — **Growth** 120/min, **Scale** 600/min, **Enterprise** unlimited — with a ceiling of 3x that rate across all of the workspace's keys. The per-IP ceiling is not the binding limit for authenticated calls. Standard `x-ratelimit-*` headers; **429** carries `Retry-After`. ## Parameters | Name | In | Required | Type | Description | |------|----|----------|------|-------------| | `id` | path | yes | string | Webhook subscription UUID (as returned at creation / by the list endpoint). | ## Responses - **200** — The test delivery was attempted (check delivered/statusCode for the receiver's response). → [WebhookTestResult](/schemas/WebhookTestResult.md) - **401** — Missing, invalid, revoked or expired credentials. → [Error](/schemas/Error.md) - **402** — The write is blocked by billing — the workspace subscription is lapsed / its grace period expired (reads are unaffected), OR (on passport-creating writes) the… → [PassportQuotaError](/schemas/PassportQuotaError.md) - **403** — Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA sessio… → [Error](/schemas/Error.md) - **404** — The resource does not exist or is not visible to the calling workspace. → [Error](/schemas/Error.md) - **429** — Rate limit exceeded — either your key's per-minute plan budget (or the 3x workspace ceiling above it) or the per-IP ceiling, whichever bit first. - **500** — Unexpected server error. → [Error](/schemas/Error.md) ## Example ```bash curl -s \ -H 'Authorization: Bearer op_dpp_token_…' \ -X POST 'https://opendpp-node.eu/api/v1/webhooks/subscriptions/{id}/test' ``` ## See also Schemas: [WebhookTestResult](/schemas/WebhookTestResult.md). ================================================================================ # FILE: /okf/schemas/index.md ================================================================================ # Schemas * [AasEnvironment](AasEnvironment.md) - An Asset Administration Shell (AAS) v3.0 environment export of the passport, served as application/aas+json. * [AasEnvironmentInput](AasEnvironmentInput.md) - An Asset Administration Shell (AAS) JSON Environment — the format produced by OpenDPP's AAS export of a passport. * [AasIngestBadRequest](AasIngestBadRequest.md) - The 400 bodies of AAS ingestion: the standard error triple (bad request / signature verification / ingestion failure), or an ESPR validatio… * [AasIngestCreated](AasIngestCreated.md) - 201 envelope of POST /api/v1/passports/aas/ingest. * [AasIngestValidationError](AasIngestValidationError.md) * [AdvisoryItem](AdvisoryItem.md) - One non-blocking advisory on a response's warnings[] (a heads-up — the request still succeeded) or notices[] (informational — something hel… * [ApproveGrantRequest](ApproveGrantRequest.md) - Approval body — only the final expiry is supplied; everything else comes from the original request. * [BatteryUnitCreateItem](BatteryUnitCreateItem.md) - One unit to serialise. * [BatteryUnitCurrentState](BatteryUnitCurrentState.md) - Latest recorded measurement of the unit (owner/grant tiers only). * [BatteryUnitDynamicDataEvent](BatteryUnitDynamicDataEvent.md) - One telemetry event in the JSON-LD dynamicData history (privileged view only). * [BatteryUnitEventBadRequest](BatteryUnitEventBadRequest.md) - The two 400 bodies of event recording: the standard error triple from handler validation, and the framework's default request-rejection bod… * [BatteryUnitEventListResponse](BatteryUnitEventListResponse.md) - One page of a battery unit's append-only dynamic-data history, newest first. * [BatteryUnitEventNode](BatteryUnitEventNode.md) - One append-only telemetry event (owner/grant tiers only). * [BatteryUnitEventRow](BatteryUnitEventRow.md) - One immutable per-unit telemetry record — the reads return exactly the fields documented here. * [BatteryUnitEventType](BatteryUnitEventType.md) - Per-unit dynamic-data event category (Annex XIII / Art. 77 telemetry). * [BatteryUnitJsonLd](BatteryUnitJsonLd.md) - JSON-LD document for one serialised battery unit, privileged tenant view (isPrivileged=true): includes currentState + dynamicData telemetry… * [BatteryUnitLineageRef](BatteryUnitLineageRef.md) - Public lineage pointer between battery units. * [BatteryUnitListResponse](BatteryUnitListResponse.md) - A page of the serialised battery units recorded under one passport, with the paging envelope. * [BatteryUnitRestrictedDataNotice](BatteryUnitRestrictedDataNotice.md) - Marker replacing per-unit telemetry in anonymous (public-tier) responses, with a pointer for requesting legitimate-interest access (Annex X… * [BatteryUnitRow](BatteryUnitRow.md) - One physical serialised battery — the reads return exactly the fields documented here. * [BatteryUnitSerialisationFailedError](BatteryUnitSerialisationFailedError.md) - 400 body when every item in the serialisation batch failed. * [BatteryUnitSerialiseBadRequest](BatteryUnitSerialiseBadRequest.md) - The three 400 bodies of unit serialisation: the standard error triple, the all-items-failed Serialisation Failed report, and the framework'… * [BatteryUnitStatus](BatteryUnitStatus.md) - Annex XIII battery-status vocabulary (EU Battery Regulation). * [BatteryUnitTombstoneJsonLd](BatteryUnitTombstoneJsonLd.md) - Tombstone (HTTP 410): once a battery is recycled its passport has ceased to exist. * [BulkBatteryUnitEventsRequest](BulkBatteryUnitEventsRequest.md) - A batch of telemetry records for one unit. * [BulkBatteryUnitEventsResponse](BulkBatteryUnitEventsResponse.md) - The partial-success report of a bulk telemetry ingest. * [CreateGrantRequest](CreateGrantRequest.md) - Direct-issuance body. * [DefaultRequestRejectionError](DefaultRequestRejectionError.md) - The default 400 body of a request rejected before the handler runs — a syntactically malformed JSON body, or an envelope (schema) violation… * [DeleteOperatorResponse](DeleteOperatorResponse.md) - Outcome of removing an economic operator: whether it was archived rather than deleted, and how many of its passports were archived with it. * [DidWebDocument](DidWebDocument.md) - A tenant's did:web DID document (public-key material only). * [DppJsonLdContextDocument](DppJsonLdContextDocument.md) - The fixed W3C JSON-LD context document served by GET /context/v1: maps DigitalProductPassport, economicOperator, metadata, digitalSeal, sig… * [DppVocabContextDocument](DppVocabContextDocument.md) - The canonical resolvable JSON-LD context served by GET /contexts/dpp/v1 — the context every public passport and battery-unit document refer… * [EconomicOperatorNode](EconomicOperatorNode.md) - Embedded economic-operator JSON-LD node (public in all tiers). * [EpcisCaptureResponse](EpcisCaptureResponse.md) - Per-event outcome of capturing an EPCIS 2.0 document, with partial-success semantics: some events may be stored while others fail. * [EpcisDocument](EpcisDocument.md) - A GS1 EPCIS 2.0 document (JSON/JSON-LD). * [Error](Error.md) - Standard error body. * [FacilityCreateRequest](FacilityCreateRequest.md) - A facility to register: its GS1 GLN-13, name and country, plus optional activity and street address. * [FacilityCreatedEnvelope](FacilityCreatedEnvelope.md) - Confirmation that a facility was registered, carrying the stored record. * [FacilityDeletedEnvelope](FacilityDeletedEnvelope.md) - Confirmation that a facility was deleted. * [FacilityEnvelope](FacilityEnvelope.md) - A single facility record. * [FacilityListEnvelope](FacilityListEnvelope.md) - A page of the workspace's facilities, with the paging envelope. * [FacilityRow](FacilityRow.md) - A facility (GS1 GLN) master-data row, exactly as stored. * [FacilityUpdateRequest](FacilityUpdateRequest.md) - Partial update. * [ForwardedResolverError](ForwardedResolverError.md) - Forwarded public-resolver body (no success field). * [ForwardedResolverRateLimitError](ForwardedResolverRateLimitError.md) - Forwarded public-resolver limiter body (no success field, no headers). * [GlobalRateLimitError](GlobalRateLimitError.md) - Global rate-limit plugin default body (with x-ratelimit-* headers). * [GrantDecisionResponse](GrantDecisionResponse.md) - Returned by deny and revoke: the updated grant, no token. * [GrantIssuedResponse](GrantIssuedResponse.md) - Returned by direct issuance (201) and request approval (200). * [GrantListResponse](GrantListResponse.md) - List envelope for GET /api/v1/grants (paginated). * [GrantRevokeForbidden](GrantRevokeForbidden.md) - The two 403 bodies of grant revocation: the route-level {error, message} body (an AUTHORITY grant cannot be revoked by the workspace; no su… * [GrantRouteError](GrantRouteError.md) - Error body used by the grants endpoints' route-level errors (400/403/404/409). * [GrantRow](GrantRow.md) - Tenant-facing projection of an access grant. * [Gs1BatchDecodeError](Gs1BatchDecodeError.md) - A per-item decode failure — the batch itself still returns 200 (partial-success). * [Gs1BatchDecodeOk](Gs1BatchDecodeOk.md) - A successfully decoded item — the same fields as the single-scan 200 minus success. * [Gs1BatchDecodeResult](Gs1BatchDecodeResult.md) - One batch-decode result, aligned to its input item: a decoded scan (ok: true) or a per-item error (ok: false + error). * [HealthStatus](HealthStatus.md) - Health-check body of GET /health. * [MaterialVocabularyListResponse](MaterialVocabularyListResponse.md) - Envelope of GET /api/v1/materials. * [MaterialVocabularyRow](MaterialVocabularyRow.md) - One entry of the platform-curated material vocabulary. * [MerkleTreeAttestationProof](MerkleTreeAttestationProof.md) - OpenDPP's own proof type — an ADVANCED electronic seal: an ECDSA prime256v1 signature over a SHA-256 Merkle root of the key-sorted metadata… * [OperatorGetResponse](OperatorGetResponse.md) - A single economic operator record. * [OperatorListResponse](OperatorListResponse.md) - The economic operators bound to the calling workspace. * [OperatorMinimalError](OperatorMinimalError.md) - Minimal error envelope used by the operator/key self-service handlers — note the standard error key is ABSENT (unlike the shared Error sche… * [OperatorMinimalErrorResponse](OperatorMinimalErrorResponse.md) - An operator-endpoint error: either the route's minimal {error, message} body (no success field) or the standard middleware envelope. * [OperatorRow](OperatorRow.md) - An economic-operator record (EconomicOperator). * [PassportAasEnvironment](PassportAasEnvironment.md) - IDTA Asset Administration Shell environment (returned when Accept contains application/aas+json), role-filtered for the caller's access tie… * [PassportBulkBadRequest](PassportBulkBadRequest.md) - The 400 bodies of bulk ingestion: every row failed (Bulk Ingestion Failed), or the request never reached row processing and returns the def… * [PassportBulkFailure](PassportBulkFailure.md) - 400 body of POST /api/v1/passports/bulk when EVERY row failed. * [PassportBulkRequest](PassportBulkRequest.md) - A batch of passports to ingest, with optional dry-run preview and upsert-on-conflict behaviour. * [PassportBulkResult](PassportBulkResult.md) - 201 partial-success envelope of POST /api/v1/passports/bulk. * [PassportBulkRow](PassportBulkRow.md) - One bulk-ingestion row. * [PassportCreateBadRequest](PassportCreateBadRequest.md) - The 400 bodies of passport creation: an ESPR validation failure with per-field errors[], or the standard error triple / pre-handler rejecti… * [PassportCreateRequest](PassportCreateRequest.md) - A passport to create: its product identifier and ESPR category metadata, with optional operator and facility binding, a draft flag, and enr… * [PassportCreateValidationError](PassportCreateValidationError.md) * [PassportEnrichmentInput](PassportEnrichmentInput.md) - Optional presentational (non-regulatory) marketing enrichment, stored OUTSIDE the ESPR-validated metadata and the Merkle seal; it never app… * [PassportGetNotFound](PassportGetNotFound.md) - The two 404 bodies of an authenticated passport read: the standard workspace-scoped envelope, or the body forwarded from the public resolve… * [PassportGetTooManyRequests](PassportGetTooManyRequests.md) - The two 429 bodies of an authenticated passport read: the global limiter's default body (with x-ratelimit-* headers), or the body forwarded… * [PassportIngestCreated](PassportIngestCreated.md) - 201 envelope of POST /api/v1/passports. * [PassportListItem](PassportListItem.md) - One JSON-LD passport document as it appears in GET /api/v1/passports list responses. * [PassportListResponse](PassportListResponse.md) - Envelope of GET /api/v1/passports. * [PassportMetadataInput](PassportMetadataInput.md) - The ESPR product metadata payload. * [PassportQuotaError](PassportQuotaError.md) - 402 body for a write blocked by billing. * [PassportSealResponse](PassportSealResponse.md) - 200 envelope of POST /api/v1/passports/{id}/seal. * [PassportStatusUpdateRequest](PassportStatusUpdateRequest.md) - Body of PUT /api/v1/passports/{id}/status. * [PassportStatusUpdateResponse](PassportStatusUpdateResponse.md) - 200 envelope of PUT /api/v1/passports/{id}/status. * [PassportUpdateBadRequest](PassportUpdateBadRequest.md) - The two 400 bodies of a passport update: the standard error triple, or an ESPR validation failure (which, unlike creation, carries NO warni… * [PassportUpdateRequest](PassportUpdateRequest.md) - Body of PUT /api/v1/passports/{id}. * [PassportUpdateResponse](PassportUpdateResponse.md) - 200 envelope of PUT /api/v1/passports/{id}. * [PassportUpdateValidationError](PassportUpdateValidationError.md) - 400 ESPR validation failure body of PUT /api/v1/passports/{id}. * [PassportValidateOnlyError](PassportValidateOnlyError.md) - 400 envelope of the validate-only endpoints. * [PassportValidateOnlyRequest](PassportValidateOnlyRequest.md) - A metadata payload to validate against its ESPR category rules without persisting anything. * [PassportValidateOnlyResult](PassportValidateOnlyResult.md) - 200 envelope of the validate-only endpoints (only the declared keys are emitted). * [PublicBatteryUnitJsonLd](PublicBatteryUnitJsonLd.md) - Public JSON-LD document for one individual serialised battery unit (EU Battery Regulation). * [PublicFacilityNode](PublicFacilityNode.md) - Embedded manufacturing-facility JSON-LD node — the GS1 GLN-backed Unique Facility Identifier (UFI, EN 18219). * [PublicPassportJsonLd](PublicPassportJsonLd.md) - The public, redacted JSON-LD Digital Product Passport document (application/ld+json). * [RecordBatteryUnitEventRequest](RecordBatteryUnitEventRequest.md) - One telemetry record. * [RecordBatteryUnitEventResponse](RecordBatteryUnitEventResponse.md) - Confirmation that a dynamic-data record was appended to a battery unit, echoing the stored event. * [RegisterOperatorRequest](RegisterOperatorRequest.md) - An economic operator to register: its legal name and registration identifier, with an optional identifier scheme and supply-chain role. * [RegisterOperatorResponse](RegisterOperatorResponse.md) - Confirmation that an economic operator was registered, carrying the stored record and any non-blocking advisories. * [RestoreOperatorResponse](RestoreOperatorResponse.md) - Outcome of restoring an archived economic operator, including how many of its passports were restored. * [RotateTenantKeysResponse](RotateTenantKeysResponse.md) - Confirmation that the workspace's signing key was rotated, returning the new public key. * [SealCertificateReport](SealCertificateReport.md) - Present only for x5c-carrying proofs on a verified: true outcome whose chain is TRUSTED — chainValid AND keyMatchesProof both true (the two… * [SealTimestampReport](SealTimestampReport.md) - Present only when payload.proof.rfc3161.token was supplied AND verification proceeds past the key-registration and operator-binding gates (… * [SealVerifyRequest](SealVerifyRequest.md) - Verification request. * [SealVerifyResponse](SealVerifyResponse.md) - Always HTTP 200 once the request is well-formed. * [SectorJsonSchemaDocument](SectorJsonSchemaDocument.md) - A JSON Schema draft-07 document describing the ESPR metadata payload for one product category, served as application/schema+json. * [SectorVocabularyContext](SectorVocabularyContext.md) - Per-category JSON-LD vocabulary context, returned by GET /api/v1/schemas/{category} when Accept contains application/ld+json. * [SerializeBatteryUnitsRequest](SerializeBatteryUnitsRequest.md) - Either a single unit object, or a batch wrapper {units: [...]}. * [SerializeBatteryUnitsResponse](SerializeBatteryUnitsResponse.md) - Returned (201) when at least one unit was created. * [ServiceVersion](ServiceVersion.md) - Running API contract version and source build identity, returned by GET /api/v1/version. * [TraceEventRegistered](TraceEventRegistered.md) - 201 envelope of POST /api/v1/events. * [TraceLineageNode](TraceLineageNode.md) - One node of the recursive upstream lineage DAG. * [TraceLineageResponse](TraceLineageResponse.md) - The upstream pedigree of a traceability event, as a recursive graph of the events it derives from. * [UntpEventCredential](UntpEventCredential.md) - A UNTP/EPCIS 2.0 traceability event wrapped as a VC-shaped credential. * [UntpEventCredentialSubject](UntpEventCredentialSubject.md) - The EPCIS event payload. * [UntpEventProof](UntpEventProof.md) - Credential proof. * [UntpVerificationMethod](UntpVerificationMethod.md) - Embedded verification-method object. * [UpdateOperatorRequest](UpdateOperatorRequest.md) - Both fields are optional. * [UpdateOperatorResponse](UpdateOperatorResponse.md) - The economic operator as stored after the update. * [ValidationErrorItem](ValidationErrorItem.md) - One field-level finding from ESPR category validation. * [WebhookDeliveriesResponse](WebhookDeliveriesResponse.md) - Recent webhook delivery attempts for a subscription, newest first, for debugging endpoint failures. * [WebhookDeliveryRow](WebhookDeliveryRow.md) - One outbox delivery record (event-level). * [WebhookEnvelope](WebhookEnvelope.md) - The signed body of every webhook delivery. * [WebhookEventFilter](WebhookEventFilter.md) - Subscribable event filter values. * [WebhookSecretRotateResponse](WebhookSecretRotateResponse.md) - Confirmation that a subscription's HMAC signing secret was rotated; the new secret is returned once and cannot be retrieved again. * [WebhookSubscriptionCreateRequest](WebhookSubscriptionCreateRequest.md) - An endpoint to receive webhook deliveries, and the event types it subscribes to. * [WebhookSubscriptionCreateResponse](WebhookSubscriptionCreateResponse.md) - Confirmation that a webhook subscription was created, carrying the stored subscription. * [WebhookSubscriptionDeleteResponse](WebhookSubscriptionDeleteResponse.md) - Confirmation that a webhook subscription was deleted. * [WebhookSubscriptionListResponse](WebhookSubscriptionListResponse.md) - The calling workspace's webhook subscriptions. * [WebhookSubscriptionRow](WebhookSubscriptionRow.md) - A webhook subscription row with the HMAC signing secret stripped (it is shown exactly once, in the 201 create response). * [WebhookSubscriptionUpdateRequest](WebhookSubscriptionUpdateRequest.md) - All fields optional; include only what you want to change. * [WebhookSubscriptionUpdateResponse](WebhookSubscriptionUpdateResponse.md) - The webhook subscription as stored after the update. * [WebhookSubscriptionWithSecret](WebhookSubscriptionWithSecret.md) - The full subscription row as returned ONLY by the 201 create response — includes the HMAC-SHA256 signing secret. * [WebhookTestResult](WebhookTestResult.md) - The outcome of delivering a signed sample event to a subscription's endpoint right now. * [WhoamiResponse](WhoamiResponse.md) - The calling credential's identity: its workspace, the resolved auth principal and permissions, and active-passport usage against the plan q… ================================================================================ # FILE: /okf/schemas/AasEnvironment.md ================================================================================ --- type: Schema title: AasEnvironment description: An Asset Administration Shell (AAS) v3.0 environment export of the passport, served as application/aas+json. resource: https://opendpp-node.eu/openapi.json#/components/schemas/AasEnvironment tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- An Asset Administration Shell (AAS) v3.0 environment export of the passport, served as `application/aas+json`. Three top-level keys: `assetAdministrationShells` (asset identity — `urn:opendpp:aas:{passportId}` / `urn:opendpp:asset:{operatorId}:{productId}`, GS1 GLN-qualified specific asset ids), `submodels`, and `conceptDescriptions` (semantic concept records from the admin-curated registry, `urn:opendpp:concept:…`; empty array when the registry is empty). Submodels: a `GeneralProductInformation` submodel (`urn:opendpp:submodel:general:{passportId}`), a `ComplianceMetadata` submodel (`urn:opendpp:submodel:compliance`) mapping the passport metadata through the concept registry, an IDTA Digital Nameplate submodel (idShort `Nameplate`) whenever manufacturer/product identity is available — carrying `ManufacturerName` / `ManufacturerProductDesignation` for downstream index discoverability — one or more additive per-category submodel views (ESPR-category views such as CarbonFootprint / TechnicalData, id prefix `urn:opendpp:submodel:category:`), and — whenever the issuing tenant's signing key is provisioned (the normal case) — an `eidasVerificationSeal` submodel (`urn:opendpp:submodel:security-seal:{passportId}`) carrying `digitalSealHash`, `cryptographicSignature`, `pemPublicKey` and an optional `x509CertificateChain`. The seal submodel is present for EVERY access tier. Role filtering strips restricted and commercial owner-only elements from the `ComplianceMetadata` submodel before sending: owner credentials are filtered by their API-key role, grant holders by the `legitimate_interest` tier, anonymous callers by the `public` tier. Submodel internals are intentionally not enumerated in this specification. ## JSON Schema ```json { "type": "object", "description": "An Asset Administration Shell (AAS) v3.0 environment export of the passport, served as `application/aas+json`. Three top-level keys: `assetAdministrationShells` (asset identity — `urn:opendpp:aas:{passportId}` / `urn:opendpp:asset:{operatorId}:{productId}`, GS1 GLN-qualified specific asset ids), `submodels`, and `conceptDescriptions` (semantic concept records from the admin-curated registry, `urn:opendpp:concept:…`; empty array when the registry is empty). Submodels: a `GeneralProductInformation` submodel (`urn:opendpp:submodel:general:{passportId}`), a `ComplianceMetadata` submodel (`urn:opendpp:submodel:compliance`) mapping the passport metadata through the concept registry, an IDTA Digital Nameplate submodel (idShort `Nameplate`) whenever manufacturer/product identity is available — carrying `ManufacturerName` / `ManufacturerProductDesignation` for downstream index discoverability — one or more additive per-category submodel views (ESPR-category views such as CarbonFootprint / TechnicalData, id prefix `urn:opendpp:submodel:category:`), and — whenever the issuing tenant's signing key is provisioned (the normal case) — an `eidasVerificationSeal` submodel (`urn:opendpp:submodel:security-seal:{passportId}`) carrying `digitalSealHash`, `cryptographicSignature`, `pemPublicKey` and an optional `x509CertificateChain`. The seal submodel is present for EVERY access tier. Role filtering strips restricted and commercial owner-only elements from the `ComplianceMetadata` submodel before sending: owner credentials are filtered by their API-key role, grant holders by the `legitimate_interest` tier, anonymous callers by the `public` tier. Submodel internals are intentionally not enumerated in this specification.", "additionalProperties": true } ``` ## Used by - [resolvePublicPassport](/operations/resolvePublicPassport.md) (`GET /passport/{id}`) - [resolveGs1Gtin](/operations/resolveGs1Gtin.md) (`GET /01/{gtin14}`) - [resolveGs1Grai](/operations/resolveGs1Grai.md) (`GET /8003/{grai}`) ================================================================================ # FILE: /okf/schemas/AasEnvironmentInput.md ================================================================================ --- type: Schema title: AasEnvironmentInput description: An Asset Administration Shell (AAS) JSON Environment — the format produced by OpenDPP's AAS export of a passport. resource: https://opendpp-node.eu/openapi.json#/components/schemas/AasEnvironmentInput tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- An Asset Administration Shell (AAS) JSON Environment — the format produced by OpenDPP's AAS export of a passport. MUST contain a submodel with `idShort: "ComplianceMetadata"` whose `submodelElements` (AAS `Property` elements and `SubmodelElementCollection`s) are parsed back into the passport metadata object; absence fails 400 `Ingestion Failed`. MAY contain an `eidasVerificationSeal` submodel (elements `digitalSealHash`, `cryptographicSignature`, `pemPublicKey`) — when present, the seal is verified against the tenant's SERVER-HELD signing public key (the embedded `pemPublicKey` is never trusted as the verification key). Body limit 256 KiB. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `assetAdministrationShells` | array | no | AAS shells. | | `submodels` | array | yes | Must include the ComplianceMetadata submodel; may include eidasVerificationSeal. | | `conceptDescriptions` | array | no | — | ## JSON Schema ```json { "type": "object", "required": [ "submodels" ], "description": "An Asset Administration Shell (AAS) JSON Environment — the format produced by OpenDPP's AAS export of a passport. MUST contain a submodel with `idShort: \"ComplianceMetadata\"` whose `submodelElements` (AAS `Property` elements and `SubmodelElementCollection`s) are parsed back into the passport metadata object; absence fails 400 `Ingestion Failed`. MAY contain an `eidasVerificationSeal` submodel (elements `digitalSealHash`, `cryptographicSignature`, `pemPublicKey`) — when present, the seal is verified against the tenant's SERVER-HELD signing public key (the embedded `pemPublicKey` is never trusted as the verification key). Body limit 256 KiB.", "properties": { "assetAdministrationShells": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "AAS shells. The first shell's `assetInformation.specificAssetIds` entry with `name: \"productId\"` is the last-resort productId source (after `metadata.gtin`/`metadata.grai`/`metadata.productId`)." }, "submodels": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Must include the `ComplianceMetadata` submodel; may include `eidasVerificationSeal`." }, "conceptDescriptions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } ``` ## Used by - [ingestPassportFromAas](/operations/ingestPassportFromAas.md) (`POST /api/v1/passports/aas/ingest`) ================================================================================ # FILE: /okf/schemas/AasIngestBadRequest.md ================================================================================ --- type: Schema title: AasIngestBadRequest description: "The 400 bodies of AAS ingestion: the standard error triple (bad request / signature verification / ingestion failure), or an ESPR validation failure with per-field errors[]." resource: https://opendpp-node.eu/openapi.json#/components/schemas/AasIngestBadRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The 400 bodies of AAS ingestion: the standard error triple (bad request / signature verification / ingestion failure), or an ESPR validation failure with per-field `errors[]`. ## JSON Schema ```json { "description": "The 400 bodies of AAS ingestion: the standard error triple (bad request / signature verification / ingestion failure), or an ESPR validation failure with per-field `errors[]`.", "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/AasIngestValidationError" } ] } ``` ## Used by - [ingestPassportFromAas](/operations/ingestPassportFromAas.md) (`POST /api/v1/passports/aas/ingest`) ================================================================================ # FILE: /okf/schemas/AasIngestCreated.md ================================================================================ --- type: Schema title: AasIngestCreated description: 201 envelope of POST /api/v1/passports/aas/ingest. resource: https://opendpp-node.eu/openapi.json#/components/schemas/AasIngestCreated tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 201 envelope of `POST /api/v1/passports/aas/ingest`. Returned for both newly created passports and in-place updates of existing UNSEALED passports. No webhook event is emitted by this endpoint. `vcReady`/`vcReadyReason` report UNTP Verifiable-Credential readiness and `warnings` carries the non-GS1 advisory, for parity with `POST /api/v1/passports`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | — | | `passportId` | string | yes | — | | `productId` | string | yes | — | | `isSealed` | boolean | yes | True when the environment embedded an eidasVerificationSeal submodel (the seal is then stored on the passport). | | `signatureVerified` | boolean | yes | True when the embedded seal verified against the tenant's server-held signing public key. | | `vcReady` | boolean | yes | Whether the ingested passport can emit a UNTP Verifiable Credential — true only when a manufacturing facility with a country of production is linked. | | `vcReadyReason` | string,null | no | Null when vcReady is true; otherwise a short, actionable reason (link a facility with a country of production). | | `warnings` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | yes | Non-blocking advisories. | ## JSON Schema ```json { "type": "object", "required": [ "success", "message", "passportId", "productId", "isSealed", "signatureVerified", "vcReady", "warnings" ], "description": "201 envelope of `POST /api/v1/passports/aas/ingest`. Returned for both newly created passports and in-place updates of existing UNSEALED passports. No webhook event is emitted by this endpoint. `vcReady`/`vcReadyReason` report UNTP Verifiable-Credential readiness and `warnings` carries the non-GS1 advisory, for parity with `POST /api/v1/passports`.", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Digital Product Passport successfully ingested from AAS" }, "passportId": { "type": "string" }, "productId": { "type": "string" }, "isSealed": { "type": "boolean", "description": "True when the environment embedded an `eidasVerificationSeal` submodel (the seal is then stored on the passport)." }, "signatureVerified": { "type": "boolean", "description": "True when the embedded seal verified against the tenant's server-held signing public key. Always false for unsealed documents. (A sealed-but-unverified document never reaches 201 — it fails 400.)" }, "vcReady": { "type": "boolean", "description": "Whether the ingested passport can emit a UNTP Verifiable Credential — true only when a manufacturing facility with a country of production is linked. AAS ingestion does not set a facility, so a newly created passport is false; an in-place update preserves whatever facility the existing passport had." }, "vcReadyReason": { "type": [ "string", "null" ], "description": "Null when `vcReady` is true; otherwise a short, actionable reason (link a facility with a country of production)." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Non-blocking advisories. Always present (empty array when none); carries the non-GS1 advisory when the resolved `productId` is not a GS1 GTIN-14/GRAI." } } } ``` ## Used by - [ingestPassportFromAas](/operations/ingestPassportFromAas.md) (`POST /api/v1/passports/aas/ingest`) ================================================================================ # FILE: /okf/schemas/AasIngestValidationError.md ================================================================================ --- type: Schema title: AAS ESPR validation failure description: AAS ESPR validation failure resource: https://opendpp-node.eu/openapi.json#/components/schemas/AasIngestValidationError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `error` | string | yes | — | | `message` | string | yes | — | | `errors` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | yes | — | | `warnings` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | no | Omitted entirely when there are no warnings. | ## JSON Schema ```json { "type": "object", "title": "AAS ESPR validation failure", "required": [ "success", "error", "message", "errors" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "Validation Failed" }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Omitted entirely when there are no warnings." } } } ``` ## Used by - schema [AasIngestBadRequest](/schemas/AasIngestBadRequest.md) ================================================================================ # FILE: /okf/schemas/AdvisoryItem.md ================================================================================ --- type: Schema title: AdvisoryItem description: One non-blocking advisory on a response's warnings[] (a heads-up — the request still succeeded) or notices[] (informational — something helpful the API did). resource: https://opendpp-node.eu/openapi.json#/components/schemas/AdvisoryItem tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One non-blocking advisory on a response's `warnings[]` (a heads-up — the request still succeeded) or `notices[]` (informational — something helpful the API did). The `code` is a MACHINE-STABLE handle an interface can switch on, map to its own localized string, or link to docs; the human `message` (developer-facing) and `friendlyMessage` (end-user, localizable) wording may change, but the code will not. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `code` | string | yes | Stable advisory code. | | `path` | string | no | The field the advisory is about (e.g. productId, draft, regId), when applicable. | | `message` | string | yes | Developer-facing detail (English). | | `friendlyMessage` | string | yes | End-user-facing, localizable summary. | ## JSON Schema ```json { "type": "object", "description": "One non-blocking advisory on a response's `warnings[]` (a heads-up — the request still succeeded) or `notices[]` (informational — something helpful the API did). The `code` is a MACHINE-STABLE handle an interface can switch on, map to its own localized string, or link to docs; the human `message` (developer-facing) and `friendlyMessage` (end-user, localizable) wording may change, but the code will not.", "required": [ "code", "message", "friendlyMessage" ], "properties": { "code": { "type": "string", "description": "Stable advisory code. WARNINGS: `NON_GS1_PRODUCT_ID` (the productId is not a GS1 GTIN/GRAI → no scannable GS1 link), `PII_SHAPE_DETECTED` (metadata looks like personal data), `UNIT_NO_SCANNABLE_LINK` (units under a non-GTIN passport have no scannable unit link), `DRAFT_DEMOTED` (draft:true took an already-published passport offline), `EORI_NOT_FOUND` (a declared EORI was not in the EU EOS register). NOTICES: `OPERATOR_AUTO_ATTRIBUTED` (operatorId omitted → the workspace's first bound operator was used), `GTIN_AUTO_COPIED` (a valid GTIN-14/GRAI productId was copied into metadata.gtin/metadata.grai).", "enum": [ "NON_GS1_PRODUCT_ID", "PII_SHAPE_DETECTED", "UNIT_NO_SCANNABLE_LINK", "DRAFT_DEMOTED", "EORI_NOT_FOUND", "OPERATOR_AUTO_ATTRIBUTED", "GTIN_AUTO_COPIED" ] }, "path": { "type": "string", "description": "The field the advisory is about (e.g. `productId`, `draft`, `regId`), when applicable." }, "message": { "type": "string", "description": "Developer-facing detail (English)." }, "friendlyMessage": { "type": "string", "description": "End-user-facing, localizable summary." } } } ``` ## Used by - schema [SerializeBatteryUnitsResponse](/schemas/SerializeBatteryUnitsResponse.md) - schema [RegisterOperatorResponse](/schemas/RegisterOperatorResponse.md) - schema [PassportIngestCreated](/schemas/PassportIngestCreated.md) - schema [PassportBulkResult](/schemas/PassportBulkResult.md) - schema [PassportUpdateResponse](/schemas/PassportUpdateResponse.md) - schema [PassportSealResponse](/schemas/PassportSealResponse.md) ================================================================================ # FILE: /okf/schemas/ApproveGrantRequest.md ================================================================================ --- type: Schema title: ApproveGrantRequest description: Approval body — only the final expiry is supplied; everything else comes from the original request. resource: https://opendpp-node.eu/openapi.json#/components/schemas/ApproveGrantRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Approval body — only the final expiry is supplied; everything else comes from the original request. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `expiresAt` | string | yes | Required. | ## JSON Schema ```json { "type": "object", "description": "Approval body — only the final expiry is supplied; everything else comes from the original request.", "required": [ "expiresAt" ], "properties": { "expiresAt": { "type": "string", "format": "date-time", "description": "Required. Date parsing is lenient (some non-ISO values may be accepted) — ISO 8601 is strongly recommended. Must be in the future and at most 366 days from now. Replaces the request's provisional 90-day expiry." } } } ``` ## Used by - [approveGrantRequest](/operations/approveGrantRequest.md) (`POST /api/v1/grants/{id}/approve`) ================================================================================ # FILE: /okf/schemas/BatteryUnitCreateItem.md ================================================================================ --- type: Schema title: BatteryUnitCreateItem description: One unit to serialise. resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitCreateItem tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One unit to serialise. Validation is per-item: an invalid item is skipped (its error string collected) without failing the rest of the batch. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `serialNumber` | string | yes | Required. | | `manufacturedAt` | string,number | no | Optional. | | `status` | [BatteryUnitStatus](/schemas/BatteryUnitStatus.md) | no | Optional initial status. | | `predecessorUnitId` | string | no | Optional lineage linkage: id of an existing unit in your tenant (any passport) that this battery was repurposed/remanufactured from. | | `predecessorStatus` | string | no | Optional; only meaningful with predecessorUnitId. | ## JSON Schema ```json { "type": "object", "description": "One unit to serialise. Validation is per-item: an invalid item is skipped (its error string collected) without failing the rest of the batch.", "properties": { "serialNumber": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,20}$", "description": "Required. The battery's real physical serial (GS1 AI-21). Trimmed, then must match `^[A-Za-z0-9._-]{1,20}$` (GS1 AI-21's 20-character maximum) — a longer serial is rejected at ingest with a per-item error. Must be unique within the passport (duplicates are skipped with an item error)." }, "manufacturedAt": { "type": [ "string", "number" ], "description": "Optional. Any value accepted by JavaScript `Date` parsing (ISO 8601 recommended; epoch milliseconds also work). Invalid dates skip the item." }, "status": { "$ref": "#/components/schemas/BatteryUnitStatus", "description": "Optional initial status. Defaults to `IN_SERVICE`. Creating a unit directly with `RECYCLED` records an already-ceased battery: `ceasedAt` is stamped at creation, the public view is a 410 tombstone, and the unit is refused as a `predecessorUnitId`.", "default": "IN_SERVICE" }, "predecessorUnitId": { "type": "string", "description": "Optional lineage linkage: id of an existing unit **in your tenant** (any passport) that this battery was repurposed/remanufactured from. A recycled predecessor is refused — the check keys on terminality (`ceasedAt` set or a terminal `status`), however the unit reached it. Atomically with creation, a `STATUS_CHANGE` event (`{status, successorUnitId, successorSerial}`) is appended to the predecessor and its status set to `predecessorStatus`." }, "predecessorStatus": { "type": "string", "enum": [ "REPURPOSED", "REMANUFACTURED", "REUSED" ], "default": "REPURPOSED", "description": "Optional; only meaningful with `predecessorUnitId`. The status the predecessor transitions to. Defaults to `REPURPOSED`." } }, "required": [ "serialNumber" ] } ``` ## Used by - schema [SerializeBatteryUnitsRequest](/schemas/SerializeBatteryUnitsRequest.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitCurrentState.md ================================================================================ --- type: Schema title: BatteryUnitCurrentState description: Latest recorded measurement of the unit (owner/grant tiers only). resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitCurrentState tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Latest recorded measurement of the unit (owner/grant tiers only). All measurement fields are `null` when the latest event did not carry them. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `stateOfHealth` | number,null | yes | State of health, percent (0-100). | | `cycleCount` | integer,null | yes | Cumulative full-equivalent charge cycles. | | `remainingCapacityAh` | number,null | yes | Measured remaining capacity in ampere-hours. | | `temperatureC` | number,null | yes | Observed temperature in degrees Celsius. | | `recordedAt` | string | yes | When the measurement was taken (client-supplied). | ## JSON Schema ```json { "type": "object", "description": "Latest recorded measurement of the unit (owner/grant tiers only). All measurement fields are `null` when the latest event did not carry them.", "required": [ "stateOfHealth", "cycleCount", "remainingCapacityAh", "temperatureC", "recordedAt" ], "properties": { "stateOfHealth": { "type": [ "number", "null" ], "description": "State of health, percent (0-100)." }, "cycleCount": { "type": [ "integer", "null" ], "description": "Cumulative full-equivalent charge cycles." }, "remainingCapacityAh": { "type": [ "number", "null" ], "description": "Measured remaining capacity in ampere-hours." }, "temperatureC": { "type": [ "number", "null" ], "description": "Observed temperature in degrees Celsius." }, "recordedAt": { "type": "string", "format": "date-time", "description": "When the measurement was taken (client-supplied)." } } } ``` ## Used by - schema [BatteryUnitJsonLd](/schemas/BatteryUnitJsonLd.md) - schema [PublicBatteryUnitJsonLd](/schemas/PublicBatteryUnitJsonLd.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitDynamicDataEvent.md ================================================================================ --- type: Schema title: BatteryUnitDynamicDataEvent description: One telemetry event in the JSON-LD dynamicData history (privileged view only). resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitDynamicDataEvent tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One telemetry event in the JSON-LD `dynamicData` history (privileged view only). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@type` | string | yes | — | | `eventType` | [BatteryUnitEventType](/schemas/BatteryUnitEventType.md) | yes | — | | `stateOfHealth` | number,null | yes | — | | `cycleCount` | integer,null | yes | — | | `remainingCapacityAh` | number,null | yes | — | | `temperatureC` | number,null | yes | — | | `payload` | object,array,null | yes | The persisted free-form payload — a JSON object or array (arrays pass the write-path typeof check), null when absent. | | `recordedAt` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "One telemetry event in the JSON-LD `dynamicData` history (privileged view only).", "properties": { "@type": { "type": "string", "const": "BatteryUnitEvent" }, "eventType": { "$ref": "#/components/schemas/BatteryUnitEventType" }, "stateOfHealth": { "type": [ "number", "null" ] }, "cycleCount": { "type": [ "integer", "null" ] }, "remainingCapacityAh": { "type": [ "number", "null" ] }, "temperatureC": { "type": [ "number", "null" ] }, "payload": { "type": [ "object", "array", "null" ], "description": "The persisted free-form payload — a JSON object **or array** (arrays pass the write-path `typeof` check), `null` when absent." }, "recordedAt": { "type": "string", "format": "date-time" } }, "required": [ "@type", "eventType", "stateOfHealth", "cycleCount", "remainingCapacityAh", "temperatureC", "payload", "recordedAt" ] } ``` ## Used by - schema [BatteryUnitJsonLd](/schemas/BatteryUnitJsonLd.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitEventBadRequest.md ================================================================================ --- type: Schema title: BatteryUnitEventBadRequest description: "The two 400 bodies of event recording: the standard error triple from handler validation, and the framework's default request-rejection body for malformed JSON." resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitEventBadRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The two 400 bodies of event recording: the standard error triple from handler validation, and the framework's default request-rejection body for malformed JSON. ## JSON Schema ```json { "description": "The two 400 bodies of event recording: the standard error triple from handler validation, and the framework's default request-rejection body for malformed JSON.", "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/DefaultRequestRejectionError" } ] } ``` ## Used by - [recordBatteryUnitEvent](/operations/recordBatteryUnitEvent.md) (`POST /api/v1/units/{id}/events`) ================================================================================ # FILE: /okf/schemas/BatteryUnitEventListResponse.md ================================================================================ --- type: Schema title: BatteryUnitEventListResponse description: One page of a battery unit's append-only dynamic-data history, newest first. resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitEventListResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One page of a battery unit's append-only dynamic-data history, newest first. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `count` | integer | yes | Equals events.length; never exceeds the page limit. | | `serialNumber` | string | yes | The unit's physical serial (GS1 AI-21 value). | | `nextCursor` | string,null | yes | Opaque cursor for the next (older) page — pass it as the cursor query parameter. | | `events` | array<[BatteryUnitEventRow](/schemas/BatteryUnitEventRow.md)> | yes | Newest first by recordedAt (ties broken by id), at most one page (limit) per response. | ## JSON Schema ```json { "description": "One page of a battery unit's append-only dynamic-data history, newest first.", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "count": { "type": "integer", "minimum": 0, "maximum": 500, "description": "Equals `events.length`; never exceeds the page `limit`." }, "serialNumber": { "type": "string", "description": "The unit's physical serial (GS1 AI-21 value)." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next (older) page — pass it as the `cursor` query parameter. `null` when this page ends the history." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitEventRow" }, "maxItems": 500, "description": "Newest first by `recordedAt` (ties broken by `id`), at most one page (`limit`) per response." } }, "required": [ "success", "count", "serialNumber", "nextCursor", "events" ] } ``` ## Used by - [listBatteryUnitEvents](/operations/listBatteryUnitEvents.md) (`GET /api/v1/units/{id}/events`) ================================================================================ # FILE: /okf/schemas/BatteryUnitEventNode.md ================================================================================ --- type: Schema title: BatteryUnitEventNode description: One append-only telemetry event (owner/grant tiers only). resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitEventNode tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One append-only telemetry event (owner/grant tiers only). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@type` | string | yes | — | | `eventType` | string | yes | — | | `stateOfHealth` | number,null | yes | Percent, 0-100. | | `cycleCount` | integer,null | yes | — | | `remainingCapacityAh` | number,null | yes | — | | `temperatureC` | number,null | yes | — | | `payload` | object,array,null | yes | Free-form additional telemetry/context supplied at ingestion. | | `recordedAt` | string | yes | When the measurement was taken (client-supplied at ingestion). | ## JSON Schema ```json { "type": "object", "description": "One append-only telemetry event (owner/grant tiers only).", "required": [ "@type", "eventType", "stateOfHealth", "cycleCount", "remainingCapacityAh", "temperatureC", "payload", "recordedAt" ], "properties": { "@type": { "type": "string", "const": "BatteryUnitEvent" }, "eventType": { "type": "string", "enum": [ "SOH_MEASUREMENT", "CHARGE_CYCLE", "STATUS_CHANGE", "NEGATIVE_EVENT", "OTHER" ] }, "stateOfHealth": { "type": [ "number", "null" ], "description": "Percent, 0-100." }, "cycleCount": { "type": [ "integer", "null" ] }, "remainingCapacityAh": { "type": [ "number", "null" ] }, "temperatureC": { "type": [ "number", "null" ] }, "payload": { "type": [ "object", "array", "null" ], "additionalProperties": true, "description": "Free-form additional telemetry/context supplied at ingestion. Ingestion accepts any JSON object OR array, so both shapes can appear here." }, "recordedAt": { "type": "string", "format": "date-time", "description": "When the measurement was taken (client-supplied at ingestion)." } } } ``` ## Used by - schema [PublicBatteryUnitJsonLd](/schemas/PublicBatteryUnitJsonLd.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitEventRow.md ================================================================================ --- type: Schema title: BatteryUnitEventRow description: One immutable per-unit telemetry record — the reads return exactly the fields documented here. resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitEventRow tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One immutable per-unit telemetry record — the reads return exactly the fields documented here. Append-only: no update or delete path exists. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | yes | — | | `batteryUnitId` | string | yes | — | | `tenantId` | string | yes | — | | `eventType` | [BatteryUnitEventType](/schemas/BatteryUnitEventType.md) | yes | — | | `stateOfHealth` | number,null | yes | State of health, percent. | | `cycleCount` | integer,null | yes | Cumulative full-equivalent cycles (truncated to an integer on write). | | `remainingCapacityAh` | number,null | yes | Measured remaining capacity, ampere-hours. | | `temperatureC` | number,null | yes | Observed temperature, °C. | | `payload` | object,array,null | yes | Free-form additional telemetry/context as persisted: a JSON object or array (both pass the server's typeof check and are stored verbatim); null when omitted or… | | `recordedAt` | string | yes | When the measurement was taken (client-supplied; server time when omitted). | | `createdAt` | string | yes | Immutable append timestamp (server-assigned). | ## JSON Schema ```json { "type": "object", "description": "One immutable per-unit telemetry record — the reads return exactly the fields documented here. Append-only: no update or delete path exists.", "properties": { "id": { "type": "string" }, "batteryUnitId": { "type": "string" }, "tenantId": { "type": "string" }, "eventType": { "$ref": "#/components/schemas/BatteryUnitEventType" }, "stateOfHealth": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "State of health, percent." }, "cycleCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative full-equivalent cycles (truncated to an integer on write)." }, "remainingCapacityAh": { "type": [ "number", "null" ], "minimum": 0, "description": "Measured remaining capacity, ampere-hours." }, "temperatureC": { "type": [ "number", "null" ], "minimum": -273.15, "maximum": 10000, "description": "Observed temperature, °C." }, "payload": { "type": [ "object", "array", "null" ], "description": "Free-form additional telemetry/context as persisted: a JSON object **or array** (both pass the server's `typeof` check and are stored verbatim); `null` when omitted or when the submitted value was dropped (any non-object, non-array value)." }, "recordedAt": { "type": "string", "format": "date-time", "description": "When the measurement was taken (client-supplied; server time when omitted)." }, "createdAt": { "type": "string", "format": "date-time", "description": "Immutable append timestamp (server-assigned)." } }, "required": [ "id", "batteryUnitId", "tenantId", "eventType", "stateOfHealth", "cycleCount", "remainingCapacityAh", "temperatureC", "payload", "recordedAt", "createdAt" ] } ``` ## Used by - schema [RecordBatteryUnitEventResponse](/schemas/RecordBatteryUnitEventResponse.md) - schema [BatteryUnitEventListResponse](/schemas/BatteryUnitEventListResponse.md) - schema [BulkBatteryUnitEventsResponse](/schemas/BulkBatteryUnitEventsResponse.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitEventType.md ================================================================================ --- type: Schema title: BatteryUnitEventType description: Per-unit dynamic-data event category (Annex XIII / Art. 77 telemetry). resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitEventType tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Per-unit dynamic-data event category (Annex XIII / Art. 77 telemetry). ## JSON Schema ```json { "type": "string", "enum": [ "SOH_MEASUREMENT", "CHARGE_CYCLE", "STATUS_CHANGE", "NEGATIVE_EVENT", "OTHER" ], "description": "Per-unit dynamic-data event category (Annex XIII / Art. 77 telemetry)." } ``` ## Used by - schema [BatteryUnitEventRow](/schemas/BatteryUnitEventRow.md) - schema [BatteryUnitDynamicDataEvent](/schemas/BatteryUnitDynamicDataEvent.md) - schema [RecordBatteryUnitEventRequest](/schemas/RecordBatteryUnitEventRequest.md) - schema [BulkBatteryUnitEventsRequest](/schemas/BulkBatteryUnitEventsRequest.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitJsonLd.md ================================================================================ --- type: Schema title: BatteryUnitJsonLd description: "JSON-LD document for one serialised battery unit, privileged tenant view (isPrivileged=true): includes currentState + dynamicData telemetry (restricted to legitimate-interest holders/authorities on the public view, where a restrictedData m…" resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitJsonLd tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- JSON-LD document for one serialised battery unit, **privileged tenant view** (`isPrivileged=true`): includes `currentState` + `dynamicData` telemetry (restricted to legitimate-interest holders/authorities on the public view, where a `restrictedData` marker appears instead — never on this endpoint). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | array | yes | JSON-LD context: the shared https://opendpp-node.eu/contexts/dpp/v1 IRI plus an inline term map for the battery-unit vocabulary. | | `@type` | string | yes | — | | `@id` | string | yes | The unit's GS1 Digital Link URI (same value as digitalLinkUri). | | `id` | string | yes | — | | `serialNumber` | string | yes | — | | `digitalLinkUri` | string | yes | — | | `status` | [BatteryUnitStatus](/schemas/BatteryUnitStatus.md) | yes | — | | `manufacturedAt` | string,null | yes | — | | `repurposedFrom` | — | yes | Predecessor link. | | `successorUnits` | array<[BatteryUnitLineageRef](/schemas/BatteryUnitLineageRef.md)> | yes | Units repurposed/remanufactured from this one. | | `ofModel` | [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) | yes | The SKU/type-level passport this unit is an instance of. | | `currentState` | — | yes | — | | `dynamicData` | array<[BatteryUnitDynamicDataEvent](/schemas/BatteryUnitDynamicDataEvent.md)> | yes | Full telemetry history, newest first by recordedAt, capped at the 500 most recent events. | | `createdAt` | string | yes | — | | `updatedAt` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "JSON-LD document for one serialised battery unit, **privileged tenant view** (`isPrivileged=true`): includes `currentState` + `dynamicData` telemetry (restricted to legitimate-interest holders/authorities on the public view, where a `restrictedData` marker appears instead — never on this endpoint).", "properties": { "@context": { "type": "array", "description": "JSON-LD context: the shared `https://opendpp-node.eu/contexts/dpp/v1` IRI plus an inline term map for the battery-unit vocabulary.", "items": { "type": [ "string", "object" ] } }, "@type": { "type": "string", "const": "BatteryUnit" }, "@id": { "type": "string", "format": "uri", "description": "The unit's GS1 Digital Link URI (same value as `digitalLinkUri`)." }, "id": { "type": "string" }, "serialNumber": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,20}$" }, "digitalLinkUri": { "type": "string", "format": "uri" }, "status": { "$ref": "#/components/schemas/BatteryUnitStatus" }, "manufacturedAt": { "type": [ "string", "null" ], "format": "date-time" }, "repurposedFrom": { "oneOf": [ { "$ref": "#/components/schemas/BatteryUnitLineageRef" }, { "type": "null" } ], "description": "Predecessor link. **Always `null` on `GET /api/v1/units/{id}`** — the authenticated handler does not load the lineage relation; use the public resolver `GET /unit/{id}` to see resolved lineage." }, "successorUnits": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitLineageRef" }, "description": "Units repurposed/remanufactured from this one. **Always `[]` on `GET /api/v1/units/{id}`** (relation not loaded; see `repurposedFrom`)." }, "ofModel": { "$ref": "#/components/schemas/PublicPassportJsonLd", "description": "The SKU/type-level passport this unit is an instance of. On this authenticated endpoint it is rendered in the **owner (privileged, unredacted) variant**: legitimate-interest-tier metadata keys and owner-only keys (e.g. `facilityDetails`) are NOT masked, unlike the anonymous public document this schema describes. The passport's own `@context` inline map always carries 9 fixed terms (DigitalProductPassport, economicOperator, manufacturingFacility, metadata, digitalSeal, signingPublicKey, status, archivedAt, retentionUntil) plus one dynamically generated term per metadata key." }, "currentState": { "oneOf": [ { "$ref": "#/components/schemas/BatteryUnitCurrentState" }, { "type": "null" } ] }, "dynamicData": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitDynamicDataEvent" }, "maxItems": 500, "description": "Full telemetry history, newest first by `recordedAt`, capped at the 500 most recent events." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "@context", "@type", "@id", "id", "serialNumber", "digitalLinkUri", "status", "manufacturedAt", "repurposedFrom", "successorUnits", "ofModel", "currentState", "dynamicData", "createdAt", "updatedAt" ] } ``` ## Used by - [getBatteryUnit](/operations/getBatteryUnit.md) (`GET /api/v1/units/{id}`) ================================================================================ # FILE: /okf/schemas/BatteryUnitLineageRef.md ================================================================================ --- type: Schema title: BatteryUnitLineageRef description: Public lineage pointer between battery units. resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitLineageRef tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Public lineage pointer between battery units. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `unitId` | string | yes | — | | `serialNumber` | string | yes | — | | `digitalLinkUri` | string | yes | — | | `unitUrl` | string | yes | Relative public unit URL: /unit/{unitId}. | ## JSON Schema ```json { "type": "object", "description": "Public lineage pointer between battery units.", "required": [ "unitId", "serialNumber", "digitalLinkUri", "unitUrl" ], "properties": { "unitId": { "type": "string" }, "serialNumber": { "type": "string" }, "digitalLinkUri": { "type": "string", "format": "uri" }, "unitUrl": { "type": "string", "description": "Relative public unit URL: `/unit/{unitId}`." } } } ``` ## Used by - schema [BatteryUnitJsonLd](/schemas/BatteryUnitJsonLd.md) - schema [PublicBatteryUnitJsonLd](/schemas/PublicBatteryUnitJsonLd.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitListResponse.md ================================================================================ --- type: Schema title: BatteryUnitListResponse description: A page of the serialised battery units recorded under one passport, with the paging envelope. resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitListResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A page of the serialised battery units recorded under one passport, with the paging envelope. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `count` | integer | yes | Number of items returned in THIS page (≤ limit). | | `productId` | string | yes | The passport's caller-supplied product identifier (GTIN-14 / GRAI / SKU). | | `units` | array<[BatteryUnitRow](/schemas/BatteryUnitRow.md)> | yes | All units of the passport, createdAt DESC. | | `page` | integer | yes | 1-based page number returned. | | `limit` | integer | yes | Effective page size (default 100, max 200). | | `total` | integer | yes | Total items matching across all pages. | | `totalPages` | integer | yes | Total number of pages (≥ 1). | ## JSON Schema ```json { "description": "A page of the serialised battery units recorded under one passport, with the paging envelope.", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "count": { "type": "integer", "description": "Number of items returned in THIS page (≤ `limit`)." }, "productId": { "type": "string", "description": "The passport's caller-supplied product identifier (GTIN-14 / GRAI / SKU)." }, "units": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitRow" }, "description": "All units of the passport, `createdAt` DESC." }, "page": { "type": "integer", "description": "1-based page number returned." }, "limit": { "type": "integer", "description": "Effective page size (default 100, max 200)." }, "total": { "type": "integer", "description": "Total items matching across all pages." }, "totalPages": { "type": "integer", "description": "Total number of pages (≥ 1)." } }, "required": [ "success", "count", "productId", "units", "page", "limit", "total", "totalPages" ] } ``` ## Used by - [listBatteryUnits](/operations/listBatteryUnits.md) (`GET /api/v1/passports/{passportId}/units`) ================================================================================ # FILE: /okf/schemas/BatteryUnitRestrictedDataNotice.md ================================================================================ --- type: Schema title: BatteryUnitRestrictedDataNotice description: Marker replacing per-unit telemetry in anonymous (public-tier) responses, with a pointer for requesting legitimate-interest access (Annex XIII(2)-(4)). resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitRestrictedDataNotice tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Marker replacing per-unit telemetry in anonymous (public-tier) responses, with a pointer for requesting legitimate-interest access (Annex XIII(2)-(4)). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `reason` | string | yes | — | | `reference` | string | yes | — | | `description` | string | yes | — | | `howToRequest` | string | yes | Relative URL /request-access?unit={unitId} where a legitimate-interest grant can be requested. | ## JSON Schema ```json { "type": "object", "description": "Marker replacing per-unit telemetry in anonymous (public-tier) responses, with a pointer for requesting legitimate-interest access (Annex XIII(2)-(4)).", "required": [ "reason", "reference", "description", "howToRequest" ], "properties": { "reason": { "type": "string", "const": "LEGITIMATE_INTEREST_REQUIRED" }, "reference": { "type": "string", "const": "Regulation (EU) 2023/1542, Annex XIII(2)-(4)" }, "description": { "type": "string", "const": "Per-unit dynamic data (state of health, cycle counts, negative events, temperature) is accessible only to persons with a legitimate interest and to authorities." }, "howToRequest": { "type": "string", "description": "Relative URL `/request-access?unit={unitId}` where a legitimate-interest grant can be requested." } } } ``` ## Used by - schema [PublicBatteryUnitJsonLd](/schemas/PublicBatteryUnitJsonLd.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitRow.md ================================================================================ --- type: Schema title: BatteryUnitRow description: One physical serialised battery — the reads return exactly the fields documented here. resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitRow tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One physical serialised battery — the reads return exactly the fields documented here. A `BatteryUnit` is an individual instance of a SKU/type-level passport, carrying its real serial in GS1 AI-21. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | yes | — | | `serialNumber` | string | yes | The battery's real physical serial number (GS1 AI-21 value). | | `digitalLinkUri` | string | yes | Per-unit GS1 Digital Link: {origin}/{01|8003}/{productId}/21/{serialNumber} — AI 01 for GTIN (and non-GS1 SKUs), 8003 for GRAI. | | `passportId` | string | yes | The SKU/type-level passport this unit is an instance of. | | `tenantId` | string | yes | Owning tenant id. | | `manufacturedAt` | string,null | yes | — | | `status` | [BatteryUnitStatus](/schemas/BatteryUnitStatus.md) | yes | — | | `ceasedAt` | string,null | yes | Stamped when the unit enters a terminal status — at creation for a unit created with initial status RECYCLED, or by the events endpoint on the RECYCLED transit… | | `predecessorUnitId` | string,null | yes | Lineage: the original unit this battery was repurposed/remanufactured from (null for first-life units). | | `createdAt` | string | yes | — | | `updatedAt` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "One physical serialised battery — the reads return exactly the fields documented here. A `BatteryUnit` is an individual instance of a SKU/type-level passport, carrying its real serial in GS1 AI-21.", "properties": { "id": { "type": "string" }, "serialNumber": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,20}$", "description": "The battery's real physical serial number (GS1 AI-21 value). 1–20 URL-safe characters; GS1 recommends ≤ 20." }, "digitalLinkUri": { "type": "string", "format": "uri", "description": "Per-unit GS1 Digital Link: `{origin}/{01|8003}/{productId}/21/{serialNumber}` — AI `01` for GTIN (and non-GS1 SKUs), `8003` for GRAI. Unique platform-wide." }, "passportId": { "type": "string", "description": "The SKU/type-level passport this unit is an instance of." }, "tenantId": { "type": "string", "description": "Owning tenant id." }, "manufacturedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/BatteryUnitStatus" }, "ceasedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Stamped when the unit enters a terminal status — at creation for a unit created with initial status `RECYCLED`, or by the events endpoint on the `RECYCLED` transition; never cleared afterwards. Non-null means the public unit view is a 410 tombstone and the unit is refused as a `predecessorUnitId`." }, "predecessorUnitId": { "type": [ "string", "null" ], "description": "Lineage: the original unit this battery was repurposed/remanufactured from (`null` for first-life units)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "serialNumber", "digitalLinkUri", "passportId", "tenantId", "manufacturedAt", "status", "ceasedAt", "predecessorUnitId", "createdAt", "updatedAt" ] } ``` ## Used by - schema [SerializeBatteryUnitsResponse](/schemas/SerializeBatteryUnitsResponse.md) - schema [BatteryUnitListResponse](/schemas/BatteryUnitListResponse.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitSerialisationFailedError.md ================================================================================ --- type: Schema title: BatteryUnitSerialisationFailedError description: 400 body when every item in the serialisation batch failed. resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitSerialisationFailedError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 400 body when **every** item in the serialisation batch failed. Note: `errors` is an array of plain strings and there is **no `message` field** (unlike the standard error triple). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `error` | string | yes | — | | `errors` | array | yes | — | ## JSON Schema ```json { "type": "object", "description": "400 body when **every** item in the serialisation batch failed. Note: `errors` is an array of plain strings and there is **no `message` field** (unlike the standard error triple).", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "Serialisation Failed" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "success", "error", "errors" ] } ``` ## Used by - schema [BatteryUnitSerialiseBadRequest](/schemas/BatteryUnitSerialiseBadRequest.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitSerialiseBadRequest.md ================================================================================ --- type: Schema title: BatteryUnitSerialiseBadRequest description: "The three 400 bodies of unit serialisation: the standard error triple, the all-items-failed Serialisation Failed report, and the framework's default request-rejection body." resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitSerialiseBadRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The three 400 bodies of unit serialisation: the standard error triple, the all-items-failed `Serialisation Failed` report, and the framework's default request-rejection body. ## JSON Schema ```json { "description": "The three 400 bodies of unit serialisation: the standard error triple, the all-items-failed `Serialisation Failed` report, and the framework's default request-rejection body.", "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/BatteryUnitSerialisationFailedError" }, { "$ref": "#/components/schemas/DefaultRequestRejectionError" } ] } ``` ## Used by - [serializeBatteryUnits](/operations/serializeBatteryUnits.md) (`POST /api/v1/passports/{passportId}/units`) ================================================================================ # FILE: /okf/schemas/BatteryUnitStatus.md ================================================================================ --- type: Schema title: BatteryUnitStatus description: Annex XIII battery-status vocabulary (EU Battery Regulation). resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitStatus tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Annex XIII battery-status vocabulary (EU Battery Regulation). `RECYCLED` means the passport has ceased to exist: the public unit view answers 410 Gone whenever `status` is `RECYCLED` **or** `ceasedAt` is set. `RECYCLED` is terminal however it is reached: a unit *created* with initial status `RECYCLED` has `ceasedAt` stamped at creation, exactly like one transitioned there via the events route (the stamp is never cleared). A terminal unit is refused as a `predecessorUnitId`, and the events endpoint refuses every further event (400 `Terminal Unit Status`), so neither `status` nor telemetry can change again. ## JSON Schema ```json { "type": "string", "enum": [ "IN_SERVICE", "DECOMMISSIONED", "RECALLED", "REPURPOSED", "REMANUFACTURED", "REUSED", "WASTE", "RECYCLED" ], "description": "Annex XIII battery-status vocabulary (EU Battery Regulation). `RECYCLED` means the passport has ceased to exist: the public unit view answers 410 Gone whenever `status` is `RECYCLED` **or** `ceasedAt` is set. `RECYCLED` is terminal however it is reached: a unit *created* with initial status `RECYCLED` has `ceasedAt` stamped at creation, exactly like one transitioned there via the events route (the stamp is never cleared). A terminal unit is refused as a `predecessorUnitId`, and the events endpoint refuses every further event (400 `Terminal Unit Status`), so neither `status` nor telemetry can change again." } ``` ## Used by - schema [BatteryUnitRow](/schemas/BatteryUnitRow.md) - schema [BatteryUnitCreateItem](/schemas/BatteryUnitCreateItem.md) - schema [BatteryUnitJsonLd](/schemas/BatteryUnitJsonLd.md) - schema [RecordBatteryUnitEventRequest](/schemas/RecordBatteryUnitEventRequest.md) ================================================================================ # FILE: /okf/schemas/BatteryUnitTombstoneJsonLd.md ================================================================================ --- type: Schema title: BatteryUnitTombstoneJsonLd description: "Tombstone (HTTP 410): once a battery is recycled its passport has ceased to exist." resource: https://opendpp-node.eu/openapi.json#/components/schemas/BatteryUnitTombstoneJsonLd tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Tombstone (HTTP 410): once a battery is recycled its passport has ceased to exist. This minimal record confirms the unit existed, that it was recycled and when, plus the (still living) model-passport link. Grants and owner credentials do not override the tombstone on the public URL; the underlying data is retained internally for the statutory retention window. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | array<—> | yes | — | | `@type` | string | yes | — | | `@id` | string | yes | — | | `id` | string | yes | — | | `serialNumber` | string | yes | — | | `status` | string | yes | — | | `ceasedAt` | string,null | yes | When the unit's passport ceased to exist (stamped when the status transitioned to RECYCLED). | | `notice` | string | yes | — | | `ofModelUrl` | string,null | yes | Relative URL of the still-living SKU/type passport: /passport/{passportId}. | ## JSON Schema ```json { "type": "object", "description": "Tombstone (HTTP 410): once a battery is recycled its passport has ceased to exist. This minimal record confirms the unit existed, that it was recycled and when, plus the (still living) model-passport link. Grants and owner credentials do not override the tombstone on the public URL; the underlying data is retained internally for the statutory retention window.", "required": [ "@context", "@type", "@id", "id", "serialNumber", "status", "ceasedAt", "notice", "ofModelUrl" ], "properties": { "@context": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] } }, "@type": { "type": "string", "const": "BatteryUnit" }, "@id": { "type": "string", "format": "uri" }, "id": { "type": "string" }, "serialNumber": { "type": "string" }, "status": { "type": "string", "const": "RECYCLED" }, "ceasedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the unit's passport ceased to exist (stamped when the status transitioned to RECYCLED)." }, "notice": { "type": "string", "const": "This battery has been recycled. Its battery passport has ceased to exist (Regulation (EU) 2023/1542, Art. 77(8))." }, "ofModelUrl": { "type": [ "string", "null" ], "description": "Relative URL of the still-living SKU/type passport: `/passport/{passportId}`." } } } ``` ## Used by - [resolvePublicBatteryUnit](/operations/resolvePublicBatteryUnit.md) (`GET /unit/{id}`) ================================================================================ # FILE: /okf/schemas/BulkBatteryUnitEventsRequest.md ================================================================================ --- type: Schema title: BulkBatteryUnitEventsRequest description: A batch of telemetry records for one unit. resource: https://opendpp-node.eu/openapi.json#/components/schemas/BulkBatteryUnitEventsRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A batch of telemetry records for one unit. Telemetry only — a record carrying `status` is refused per-item; status transitions go through the single-event endpoint. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `events` | array | yes | — | ## JSON Schema ```json { "description": "A batch of telemetry records for one unit. Telemetry only — a record carrying `status` is refused per-item; status transitions go through the single-event endpoint.", "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "eventType" ], "properties": { "eventType": { "$ref": "#/components/schemas/BatteryUnitEventType" }, "stateOfHealth": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "State of Health, %." }, "cycleCount": { "type": [ "number", "null" ], "minimum": 0, "description": "Cumulative full-equivalent cycles; truncated to an integer before persisting." }, "remainingCapacityAh": { "type": [ "number", "null" ], "minimum": 0, "description": "Measured remaining capacity, Ah." }, "temperatureC": { "type": [ "number", "null" ], "minimum": -273.15, "maximum": 10000, "description": "Observed temperature, °C." }, "payload": { "type": [ "object", "array", "null" ], "description": "Free-form context, persisted verbatim; any non-object, non-array value is dropped (stored as `null`)." }, "recordedAt": { "type": "string", "format": "date-time", "description": "When the measurement was taken; defaults to server time when omitted." } } } } } } ``` ## Used by - [bulkRecordBatteryUnitEvents](/operations/bulkRecordBatteryUnitEvents.md) (`POST /api/v1/units/{id}/events/bulk`) ================================================================================ # FILE: /okf/schemas/BulkBatteryUnitEventsResponse.md ================================================================================ --- type: Schema title: BulkBatteryUnitEventsResponse description: The partial-success report of a bulk telemetry ingest. resource: https://opendpp-node.eu/openapi.json#/components/schemas/BulkBatteryUnitEventsResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The partial-success report of a bulk telemetry ingest. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | — | | `count` | integer | yes | How many records were accepted — equals events.length. | | `events` | array<[BatteryUnitEventRow](/schemas/BatteryUnitEventRow.md)> | yes | The persisted rows, in the order the accepted records appeared in the request. | | `errors` | array | yes | Skipped records as [index]-prefixed reasons; empty when the whole batch was accepted. | ## JSON Schema ```json { "description": "The partial-success report of a bulk telemetry ingest.", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "count": { "type": "integer", "minimum": 1, "maximum": 500, "description": "How many records were accepted — equals `events.length`." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitEventRow" }, "maxItems": 500, "description": "The persisted rows, in the order the accepted records appeared in the request." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Skipped records as `[index]`-prefixed reasons; empty when the whole batch was accepted." } }, "required": [ "success", "message", "count", "events", "errors" ] } ``` ## Used by - [bulkRecordBatteryUnitEvents](/operations/bulkRecordBatteryUnitEvents.md) (`POST /api/v1/units/{id}/events/bulk`) ================================================================================ # FILE: /okf/schemas/CreateGrantRequest.md ================================================================================ --- type: Schema title: CreateGrantRequest description: Direct-issuance body. resource: https://opendpp-node.eu/openapi.json#/components/schemas/CreateGrantRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Direct-issuance body. Over-length strings are silently truncated to the documented maximum, not rejected; unknown fields are ignored. The grant kind is always `LEGITIMATE_INTEREST` — there is no `kind`/`type` field. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `granteeName` | string | yes | Required (whitespace-only is rejected as missing). | | `granteeEmail` | string | no | Optional. | | `organization` | string | no | Optional. | | `purpose` | string | no | Optional stated legitimate interest. | | `scopeType` | string | yes | Required. | | `passportId` | string | no | Required when scopeType is PASSPORT; ignored otherwise. | | `batteryUnitId` | string | no | Required when scopeType is UNIT; ignored otherwise. | | `expiresAt` | string | yes | Required. | ## JSON Schema ```json { "type": "object", "description": "Direct-issuance body. Over-length strings are silently truncated to the documented maximum, not rejected; unknown fields are ignored. The grant kind is always `LEGITIMATE_INTEREST` — there is no `kind`/`type` field.", "required": [ "granteeName", "scopeType", "expiresAt" ], "properties": { "granteeName": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Required (whitespace-only is rejected as missing). Truncated to 160 characters." }, "granteeEmail": { "type": "string", "format": "email", "maxLength": 254, "description": "Optional. Truncated to 254 characters, then must match a basic e-mail pattern (`x@y.z`) or the request fails with 400 `granteeEmail is invalid`. Stored as given (not lowercased)." }, "organization": { "type": "string", "maxLength": 200, "description": "Optional. Truncated to 200 characters." }, "purpose": { "type": "string", "maxLength": 2000, "description": "Optional stated legitimate interest. Truncated to 2000 characters." }, "scopeType": { "type": "string", "enum": [ "UNIT", "PASSPORT", "TENANT" ], "description": "Required. `UNIT` needs `batteryUnitId`; `PASSPORT` needs `passportId`; `TENANT` is workspace-wide. Any other value ⇒ 400." }, "passportId": { "type": "string", "maxLength": 64, "description": "Required when `scopeType` is `PASSPORT`; ignored otherwise. Must be a non-DRAFT passport in this workspace — a missing, cross-tenant, or `DRAFT` id (or omitting the field entirely) returns 404." }, "batteryUnitId": { "type": "string", "maxLength": 64, "description": "Required when `scopeType` is `UNIT`; ignored otherwise. Must be a battery unit in this workspace — a missing or cross-tenant id (or omitting the field entirely) returns 404." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Required. Date parsing is lenient (some non-ISO values may be accepted) — ISO 8601 is strongly recommended. Must be in the future and at most 366 days from now." } } } ``` ## Used by - [createGrant](/operations/createGrant.md) (`POST /api/v1/grants`) ================================================================================ # FILE: /okf/schemas/DefaultRequestRejectionError.md ================================================================================ --- type: Schema title: Default request-rejection error body description: The default 400 body of a request rejected before the handler runs — a syntactically malformed JSON body, or an envelope (schema) violation — so none of the handler-built {success:false, ...} shapes apply. resource: https://opendpp-node.eu/openapi.json#/components/schemas/DefaultRequestRejectionError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The default 400 body of a request rejected **before the handler runs** — a syntactically malformed JSON body, or an envelope (schema) violation — so none of the handler-built `{success:false, ...}` shapes apply. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `statusCode` | integer | yes | — | | `code` | string | no | Machine-readable error code, e.g. FST_ERR_VALIDATION (an envelope/schema violation) or FST_ERR_CTP_INVALID_JSON_BODY (a syntactically malformed JSON body); may… | | `error` | string | yes | — | | `message` | string | yes | — | ## JSON Schema ```json { "type": "object", "title": "Default request-rejection error body", "description": "The default 400 body of a request rejected **before the handler runs** — a syntactically malformed JSON body, or an envelope (schema) violation — so none of the handler-built `{success:false, ...}` shapes apply.", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer", "const": 400 }, "code": { "type": "string", "description": "Machine-readable error code, e.g. `FST_ERR_VALIDATION` (an envelope/schema violation) or `FST_ERR_CTP_INVALID_JSON_BODY` (a syntactically malformed JSON body); may be absent.", "examples": [ "FST_ERR_VALIDATION" ] }, "error": { "type": "string", "const": "Bad Request" }, "message": { "type": "string" } } } ``` ## Used by - schema [BatteryUnitSerialiseBadRequest](/schemas/BatteryUnitSerialiseBadRequest.md) - schema [BatteryUnitEventBadRequest](/schemas/BatteryUnitEventBadRequest.md) - schema [PassportBulkBadRequest](/schemas/PassportBulkBadRequest.md) ================================================================================ # FILE: /okf/schemas/DeleteOperatorResponse.md ================================================================================ --- type: Schema title: DeleteOperatorResponse description: "Outcome of removing an economic operator: whether it was archived rather than deleted, and how many of its passports were archived with it." resource: https://opendpp-node.eu/openapi.json#/components/schemas/DeleteOperatorResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Outcome of removing an economic operator: whether it was archived rather than deleted, and how many of its passports were archived with it. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `archived` | boolean | yes | true = the operator was archived (soft-deleted; passports retained, restorable). | | `archivedPassports` | integer | no | Number of active passports archived alongside the operator. | ## JSON Schema ```json { "description": "Outcome of removing an economic operator: whether it was archived rather than deleted, and how many of its passports were archived with it.", "type": "object", "required": [ "success", "archived" ], "properties": { "success": { "type": "boolean", "const": true }, "archived": { "type": "boolean", "description": "`true` = the operator was archived (soft-deleted; passports retained, restorable). `false` = the operator was hard-deleted (it had no passports)." }, "archivedPassports": { "type": "integer", "minimum": 0, "description": "Number of active passports archived alongside the operator. Present only on the primary archive path (operator had passports); absent on hard deletes and on the foreign-key fallback archive." } } } ``` ## Used by - [deleteOperator](/operations/deleteOperator.md) (`DELETE /api/v1/operators/{id}`) ================================================================================ # FILE: /okf/schemas/DidWebDocument.md ================================================================================ --- type: Schema title: DidWebDocument description: A tenant's did:web DID document (public-key material only). resource: https://opendpp-node.eu/openapi.json#/components/schemas/DidWebDocument tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A tenant's `did:web` DID document (public-key material only). Verification methods are `JsonWebKey2020` entries with stable `#key-` ids; current and retired keys are both listed so pre-rotation credentials still verify. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | array | yes | JSON-LD contexts: the DID core context plus the JWS-2020 suite. | | `id` | string | yes | The workspace DID, did:web:opendpp-node.eu:tenants:{tenantId}. | | `name` | string | no | The issuer's authoritative legal name (present when the workspace has a company name). | | `verificationMethod` | array | yes | Public verification keys. | | `assertionMethod` | array | yes | Verification-method ids authorized to assert credentials (current + retired keys). | | `authentication` | array | yes | — | ## JSON Schema ```json { "type": "object", "description": "A tenant's `did:web` DID document (public-key material only). Verification methods are `JsonWebKey2020` entries with stable `#key-` ids; current and retired keys are both listed so pre-rotation credentials still verify.", "required": [ "@context", "id", "verificationMethod", "assertionMethod", "authentication" ], "properties": { "@context": { "type": "array", "items": { "type": "string" }, "description": "JSON-LD contexts: the DID core context plus the JWS-2020 suite." }, "id": { "type": "string", "description": "The workspace DID, `did:web:opendpp-node.eu:tenants:{tenantId}`." }, "name": { "type": "string", "description": "The issuer's authoritative legal name (present when the workspace has a company name)." }, "verificationMethod": { "type": "array", "description": "Public verification keys.", "items": { "type": "object", "required": [ "id", "type", "controller", "publicKeyJwk" ], "properties": { "id": { "type": "string", "description": "`#key-` — matches the credential `kid`." }, "type": { "type": "string", "enum": [ "JsonWebKey2020" ] }, "controller": { "type": "string" }, "publicKeyJwk": { "type": "object", "description": "The public key as a JWK (EC P-256, `alg: ES256`, `use: sig`). Public material only." } } } }, "assertionMethod": { "type": "array", "items": { "type": "string" }, "description": "Verification-method ids authorized to assert credentials (current + retired keys)." }, "authentication": { "type": "array", "items": { "type": "string" } } } } ``` ## Used by - [getTenantDidDocument](/operations/getTenantDidDocument.md) (`GET /tenants/{tenantId}/did.json`) ================================================================================ # FILE: /okf/schemas/DppJsonLdContextDocument.md ================================================================================ --- type: Schema title: DppJsonLdContextDocument description: "The fixed W3C JSON-LD context document served by GET /context/v1: maps DigitalProductPassport, economicOperator, metadata, digitalSeal, signingPublicKey and proof to https://opendpp-node.eu/ns/dpp#… IRIs, and createdAt/updatedAt to schema.…" resource: https://opendpp-node.eu/openapi.json#/components/schemas/DppJsonLdContextDocument tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The fixed W3C JSON-LD context document served by `GET /context/v1`: maps `DigitalProductPassport`, `economicOperator`, `metadata`, `digitalSeal`, `signingPublicKey` and `proof` to `https://opendpp-node.eu/ns/dpp#…` IRIs, and `createdAt`/`updatedAt` to schema.org `dateCreated`/`dateModified`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | object | yes | — | ## JSON Schema ```json { "type": "object", "description": "The fixed W3C JSON-LD context document served by `GET /context/v1`: maps `DigitalProductPassport`, `economicOperator`, `metadata`, `digitalSeal`, `signingPublicKey` and `proof` to `https://opendpp-node.eu/ns/dpp#…` IRIs, and `createdAt`/`updatedAt` to schema.org `dateCreated`/`dateModified`.", "required": [ "@context" ], "properties": { "@context": { "type": "object", "additionalProperties": { "type": "string" } } } } ``` ## Used by - [getJsonLdContext](/operations/getJsonLdContext.md) (`GET /context/v1`) ================================================================================ # FILE: /okf/schemas/DppVocabContextDocument.md ================================================================================ --- type: Schema title: DppVocabContextDocument description: The canonical resolvable JSON-LD context served by GET /contexts/dpp/v1 — the context every public passport and battery-unit document references in its @context. resource: https://opendpp-node.eu/openapi.json#/components/schemas/DppVocabContextDocument tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The canonical resolvable JSON-LD context served by `GET /contexts/dpp/v1` — the context every public passport and battery-unit document references in its `@context`. Declares `@vocab` (so unknown terms expand under the OpenDPP namespace) plus core term mappings; `@version` is the numeric JSON-LD 1.1 marker, so `@context` values are a mix of strings and that number. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | object | yes | Term map: @vocab + @version (1.1) + the core DPP/unit term → dpp: CURIE mappings. | ## JSON Schema ```json { "type": "object", "description": "The canonical resolvable JSON-LD context served by `GET /contexts/dpp/v1` — the context every public passport and battery-unit document references in its `@context`. Declares `@vocab` (so unknown terms expand under the OpenDPP namespace) plus core term mappings; `@version` is the numeric JSON-LD 1.1 marker, so `@context` values are a mix of strings and that number.", "required": [ "@context" ], "properties": { "@context": { "type": "object", "description": "Term map: `@vocab` + `@version` (1.1) + the core DPP/unit term → `dpp:` CURIE mappings." } } } ``` ## Used by - [getDppJsonLdContext](/operations/getDppJsonLdContext.md) (`GET /contexts/dpp/v1`) ================================================================================ # FILE: /okf/schemas/EconomicOperatorNode.md ================================================================================ --- type: Schema title: EconomicOperatorNode description: Embedded economic-operator JSON-LD node (public in all tiers). resource: https://opendpp-node.eu/openapi.json#/components/schemas/EconomicOperatorNode tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Embedded economic-operator JSON-LD node (public in all tiers). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@type` | string | yes | — | | `id` | string | yes | — | | `name` | string | yes | — | | `regId` | string | yes | EORI number or official business-registry identifier (unique platform-wide), e.g. EU-DEFAULT-001. | | `role` | string | no | Operator role in the supply chain, e.g. MANUFACTURER, IMPORTER, RETAILER. | ## JSON Schema ```json { "type": "object", "description": "Embedded economic-operator JSON-LD node (public in all tiers).", "required": [ "@type", "id", "name", "regId" ], "properties": { "@type": { "type": "string", "const": "EconomicOperator" }, "id": { "type": "string" }, "name": { "type": "string" }, "regId": { "type": "string", "description": "EORI number or official business-registry identifier (unique platform-wide), e.g. `EU-DEFAULT-001`." }, "role": { "type": "string", "description": "Operator role in the supply chain, e.g. `MANUFACTURER`, `IMPORTER`, `RETAILER`. Always present in detail/resolution responses; absent from `GET /api/v1/passports` list items." } } } ``` ## Used by - schema [PassportListItem](/schemas/PassportListItem.md) - schema [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) ================================================================================ # FILE: /okf/schemas/EpcisCaptureResponse.md ================================================================================ --- type: Schema title: EpcisCaptureResponse description: "Per-event outcome of capturing an EPCIS 2.0 document, with partial-success semantics: some events may be stored while others fail." resource: https://opendpp-node.eu/openapi.json#/components/schemas/EpcisCaptureResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Per-event outcome of capturing an EPCIS 2.0 document, with partial-success semantics: some events may be stored while others fail. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `status` | string | yes | — | | `captured` | integer | yes | How many events were persisted. | | `results` | array | yes | — | | `errors` | array | yes | — | ## JSON Schema ```json { "description": "Per-event outcome of capturing an EPCIS 2.0 document, with partial-success semantics: some events may be stored while others fail.", "type": "object", "required": [ "status", "captured", "results", "errors" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "captured": { "type": "integer", "description": "How many events were persisted." }, "results": { "type": "array", "items": { "type": "object", "required": [ "index", "eventId", "eventType" ], "properties": { "index": { "type": "integer", "description": "Position of the event in the submitted eventList." }, "eventId": { "type": "string", "description": "Server-generated row id (UUID) — the authoritative event identity on this node." }, "eventType": { "type": "string" }, "ignoredFields": { "type": "array", "items": { "type": "string" }, "description": "Recognized EPCIS fields present on the event that this node does not persist — disclosed, never silently dropped." } } } }, "errors": { "type": "array", "items": { "type": "object", "required": [ "index", "message" ], "properties": { "index": { "type": "integer" }, "message": { "type": "string" } } } } } } ``` ## Used by - [captureEpcisDocument](/operations/captureEpcisDocument.md) (`POST /api/v1/events/epcis`) ================================================================================ # FILE: /okf/schemas/EpcisDocument.md ================================================================================ --- type: Schema title: EpcisDocument description: A GS1 EPCIS 2.0 document (JSON/JSON-LD). resource: https://opendpp-node.eu/openapi.json#/components/schemas/EpcisDocument tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A GS1 EPCIS 2.0 document (JSON/JSON-LD). This shape is indicative — the OFFICIAL GS1 EPCIS 2.0.1 JSON Schema (vendored on the node, $id https://ref.gs1.org/standards/epcis/2.0.1/epcis-json-schema.json) is authoritative and is what capture validates against. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | — | yes | JSON-LD context — include https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld. | | `type` | string | yes | — | | `schemaVersion` | string | yes | — | | `creationDate` | string | yes | — | | `epcisBody` | object | yes | — | ## JSON Schema ```json { "type": "object", "description": "A GS1 EPCIS 2.0 document (JSON/JSON-LD). This shape is indicative — the OFFICIAL GS1 EPCIS 2.0.1 JSON Schema (vendored on the node, $id https://ref.gs1.org/standards/epcis/2.0.1/epcis-json-schema.json) is authoritative and is what capture validates against.", "required": [ "@context", "type", "schemaVersion", "creationDate", "epcisBody" ], "properties": { "@context": { "description": "JSON-LD context — include https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld.", "oneOf": [ { "type": "string" }, { "type": "array", "items": {} } ] }, "type": { "type": "string", "enum": [ "EPCISDocument" ] }, "schemaVersion": { "type": "string", "example": "2.0" }, "creationDate": { "type": "string", "format": "date-time" }, "epcisBody": { "type": "object", "required": [ "eventList" ], "properties": { "eventList": { "type": "array", "items": { "type": "object", "description": "One EPCIS 2.0 event (ObjectEvent, AggregationEvent, TransformationEvent, AssociationEvent — per the official schema).", "additionalProperties": true } } } } }, "additionalProperties": true } ``` ## Used by - [captureEpcisDocument](/operations/captureEpcisDocument.md) (`POST /api/v1/events/epcis`) - [getEventLineage](/operations/getEventLineage.md) (`GET /api/v1/events/{id}/lineage`) ================================================================================ # FILE: /okf/schemas/Error.md ================================================================================ --- type: Schema title: Error description: Standard error body. resource: https://opendpp-node.eu/openapi.json#/components/schemas/Error tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Standard error body. Authenticated-API errors include `success: false`; some endpoints (and all public resolution errors) omit `success` and return only `error` + `message`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | no | Always false when present. | | `error` | string | yes | Short error title (usually the HTTP reason phrase). | | `message` | string | yes | Human-readable explanation. | | `requestId` | string | no | Correlation id for this request, also returned as the X-Request-Id response header on EVERY response. | | `code` | string | no | Optional MACHINE-STABLE error code for the developer-facing write/ingest surface (passport / operator / unit / resolver / facility / events / webhooks) — branc… | ## JSON Schema ```json { "type": "object", "description": "Standard error body. Authenticated-API errors include `success: false`; some endpoints (and all public resolution errors) omit `success` and return only `error` + `message`.", "required": [ "error", "message" ], "properties": { "success": { "type": "boolean", "description": "Always `false` when present. Omitted by public endpoints and some self-service endpoints." }, "error": { "type": "string", "description": "Short error title (usually the HTTP reason phrase).", "examples": [ "Bad Request", "Not Found", "Validation Failed" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "requestId": { "type": "string", "description": "Correlation id for this request, also returned as the `X-Request-Id` response header on EVERY response. Present in generic (server-error / framework) bodies; quote it to support to correlate with server logs. Adopts a well-formed inbound `X-Request-Id` if you send one." }, "code": { "type": "string", "description": "Optional MACHINE-STABLE error code for the developer-facing write/ingest surface (passport / operator / unit / resolver / facility / events / webhooks) — branch on this instead of parsing `message`. Present on the errors it covers — the `code` enum below is the full set — and omitted otherwise.", "enum": [ "OPERATOR_NOT_BOUND", "OPERATOR_AMBIGUOUS", "OPERATOR_SCOPE_FORBIDDEN", "GTIN_CHECK_DIGIT_INVALID", "GLN_CHECK_DIGIT_INVALID", "COMPRESSED_DIGITAL_LINK", "PASSPORT_DUPLICATE", "PASSPORT_SEALED_IMMUTABLE", "CATEGORY_IMMUTABLE", "FACILITY_NOT_FOUND", "FACILITY_DUPLICATE", "WEBHOOK_NOT_FOUND", "WEBHOOK_LIMIT_REACHED", "WEBHOOK_URL_REJECTED" ] } } } ``` ## Used by - [whoami](/operations/whoami.md) (`GET /api/v1/whoami`) - [validateBatteryUnits](/operations/validateBatteryUnits.md) (`POST /api/v1/passports/{passportId}/units/validate`) - [deleteBatteryUnit](/operations/deleteBatteryUnit.md) (`DELETE /api/v1/units/{id}`) - [listBatteryUnitEvents](/operations/listBatteryUnitEvents.md) (`GET /api/v1/units/{id}/events`) - [recordBatteryUnitEvent](/operations/recordBatteryUnitEvent.md) (`POST /api/v1/units/{id}/events`) - [bulkRecordBatteryUnitEvents](/operations/bulkRecordBatteryUnitEvents.md) (`POST /api/v1/units/{id}/events/bulk`) - [createFacility](/operations/createFacility.md) (`POST /api/v1/facilities`) - [getFacility](/operations/getFacility.md) (`GET /api/v1/facilities/{id}`) - [updateFacility](/operations/updateFacility.md) (`PUT /api/v1/facilities/{id}`) - [deleteFacility](/operations/deleteFacility.md) (`DELETE /api/v1/facilities/{id}`) - [updateOperator](/operations/updateOperator.md) (`PATCH /api/v1/operators/{id}`) - [deleteOperator](/operations/deleteOperator.md) (`DELETE /api/v1/operators/{id}`) - [restoreOperator](/operations/restoreOperator.md) (`POST /api/v1/operators/{id}/restore`) - [createPassport](/operations/createPassport.md) (`POST /api/v1/passports`) - [getPassport](/operations/getPassport.md) (`GET /api/v1/passports/{id}`) - [updatePassport](/operations/updatePassport.md) (`PUT /api/v1/passports/{id}`) - [deleteDraftPassport](/operations/deleteDraftPassport.md) (`DELETE /api/v1/passports/{id}`) - [sealPassport](/operations/sealPassport.md) (`POST /api/v1/passports/{id}/seal`) - [updatePassportStatus](/operations/updatePassportStatus.md) (`PUT /api/v1/passports/{id}/status`) - [resolvePublicPassport](/operations/resolvePublicPassport.md) (`GET /passport/{id}`) - [resolveGs1Gtin](/operations/resolveGs1Gtin.md) (`GET /01/{gtin14}`) - [resolveGs1GtinSerial](/operations/resolveGs1GtinSerial.md) (`GET /01/{gtin14}/21/{serial}`) - [resolveGs1Grai](/operations/resolveGs1Grai.md) (`GET /8003/{grai}`) - [resolvePublicBatteryUnit](/operations/resolvePublicBatteryUnit.md) (`GET /unit/{id}`) - [getSealCaCertificate](/operations/getSealCaCertificate.md) (`GET /.well-known/opendpp-seal-ca.pem`) - [decodeGs1](/operations/decodeGs1.md) (`POST /api/v1/gs1/decode`) - [decodeGs1Batch](/operations/decodeGs1Batch.md) (`POST /api/v1/gs1/decode/batch`) - [getPassportQrCode](/operations/getPassportQrCode.md) (`GET /api/v1/passports/{id}/qr`) - [bulkExportPassportLabels](/operations/bulkExportPassportLabels.md) (`POST /api/v1/passports/labels`) - [getBatteryUnitQrCode](/operations/getBatteryUnitQrCode.md) (`GET /api/v1/units/{id}/qr`) - [registerTraceabilityEvent](/operations/registerTraceabilityEvent.md) (`POST /api/v1/events`) - [captureEpcisDocument](/operations/captureEpcisDocument.md) (`POST /api/v1/events/epcis`) - [getEventLineage](/operations/getEventLineage.md) (`GET /api/v1/events/{id}/lineage`) - [getTenantDidDocument](/operations/getTenantDidDocument.md) (`GET /tenants/{tenantId}/did.json`) - [getTenantRevocationStatusList](/operations/getTenantRevocationStatusList.md) (`GET /tenants/{tenantId}/status/revocation`) - [listWebhookSubscriptions](/operations/listWebhookSubscriptions.md) (`GET /api/v1/webhooks/subscriptions`) - [createWebhookSubscription](/operations/createWebhookSubscription.md) (`POST /api/v1/webhooks/subscriptions`) - [updateWebhookSubscription](/operations/updateWebhookSubscription.md) (`PATCH /api/v1/webhooks/subscriptions/{id}`) - [deleteWebhookSubscription](/operations/deleteWebhookSubscription.md) (`DELETE /api/v1/webhooks/subscriptions/{id}`) - schema [BatteryUnitSerialiseBadRequest](/schemas/BatteryUnitSerialiseBadRequest.md) - schema [BatteryUnitEventBadRequest](/schemas/BatteryUnitEventBadRequest.md) - schema [GrantRevokeForbidden](/schemas/GrantRevokeForbidden.md) - schema [OperatorMinimalErrorResponse](/schemas/OperatorMinimalErrorResponse.md) - schema [PassportCreateBadRequest](/schemas/PassportCreateBadRequest.md) - schema [AasIngestBadRequest](/schemas/AasIngestBadRequest.md) - schema [PassportGetNotFound](/schemas/PassportGetNotFound.md) - schema [PassportUpdateBadRequest](/schemas/PassportUpdateBadRequest.md) - the shared error responses ================================================================================ # FILE: /okf/schemas/FacilityCreateRequest.md ================================================================================ --- type: Schema title: FacilityCreateRequest description: "A facility to register: its GS1 GLN-13, name and country, plus optional activity and street address." resource: https://opendpp-node.eu/openapi.json#/components/schemas/FacilityCreateRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A facility to register: its GS1 GLN-13, name and country, plus optional activity and street address. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `gln` | string | yes | GS1 GLN-13. | | `name` | string | yes | Facility name. | | `country` | string | yes | 2-letter ISO country code (case-insensitive on input; stored uppercase). | | `activity` | string | no | Optional activity, e.g. "Cell assembly". | | `streetAddress` | string | no | Optional street address (owner-only in public views). | | `city` | string | no | Optional city (owner-only in public views). | | `postalCode` | string | no | Optional postal code (owner-only in public views). | | `operatorId` | string | no | Optional owning Economic Operator id. | ## JSON Schema ```json { "description": "A facility to register: its GS1 GLN-13, name and country, plus optional activity and street address.", "type": "object", "required": [ "gln", "name", "country" ], "properties": { "gln": { "type": "string", "pattern": "^[0-9]{13}$", "description": "GS1 GLN-13. Trimmed, then validated: exactly 13 digits with a valid GS1 modulo-10 check digit. Unique platform-wide (409 on duplicate). Immutable after registration." }, "name": { "type": "string", "minLength": 1, "description": "Facility name. Must be a non-empty string; stored trimmed." }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "2-letter ISO country code (case-insensitive on input; stored uppercase)." }, "activity": { "type": "string", "description": "Optional activity, e.g. \"Cell assembly\". Trimmed; empty/whitespace is stored as null." }, "streetAddress": { "type": "string", "description": "Optional street address (owner-only in public views). Trimmed; empty is stored as null." }, "city": { "type": "string", "description": "Optional city (owner-only in public views). Trimmed; empty is stored as null." }, "postalCode": { "type": "string", "description": "Optional postal code (owner-only in public views). Trimmed; empty is stored as null." }, "operatorId": { "type": "string", "description": "Optional owning Economic Operator id. Must be bound to your tenant workspace (403 otherwise). Empty/whitespace is treated as absent. Operator-scoped API keys may only use their own operator id (it is applied automatically when omitted)." } } } ``` ## Used by - [createFacility](/operations/createFacility.md) (`POST /api/v1/facilities`) ================================================================================ # FILE: /okf/schemas/FacilityCreatedEnvelope.md ================================================================================ --- type: Schema title: FacilityCreatedEnvelope description: Confirmation that a facility was registered, carrying the stored record. resource: https://opendpp-node.eu/openapi.json#/components/schemas/FacilityCreatedEnvelope tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Confirmation that a facility was registered, carrying the stored record. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | — | | `facility` | [FacilityRow](/schemas/FacilityRow.md) | yes | — | ## JSON Schema ```json { "description": "Confirmation that a facility was registered, carrying the stored record.", "type": "object", "required": [ "success", "message", "facility" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Facility registered successfully" }, "facility": { "$ref": "#/components/schemas/FacilityRow" } } } ``` ## Used by - [createFacility](/operations/createFacility.md) (`POST /api/v1/facilities`) ================================================================================ # FILE: /okf/schemas/FacilityDeletedEnvelope.md ================================================================================ --- type: Schema title: FacilityDeletedEnvelope description: Confirmation that a facility was deleted. resource: https://opendpp-node.eu/openapi.json#/components/schemas/FacilityDeletedEnvelope tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Confirmation that a facility was deleted. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | ## JSON Schema ```json { "description": "Confirmation that a facility was deleted.", "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true } } } ``` ## Used by - [deleteFacility](/operations/deleteFacility.md) (`DELETE /api/v1/facilities/{id}`) ================================================================================ # FILE: /okf/schemas/FacilityEnvelope.md ================================================================================ --- type: Schema title: FacilityEnvelope description: A single facility record. resource: https://opendpp-node.eu/openapi.json#/components/schemas/FacilityEnvelope tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A single facility record. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `facility` | [FacilityRow](/schemas/FacilityRow.md) | yes | — | ## JSON Schema ```json { "description": "A single facility record.", "type": "object", "required": [ "success", "facility" ], "properties": { "success": { "type": "boolean", "const": true }, "facility": { "$ref": "#/components/schemas/FacilityRow" } } } ``` ## Used by - [getFacility](/operations/getFacility.md) (`GET /api/v1/facilities/{id}`) - [updateFacility](/operations/updateFacility.md) (`PUT /api/v1/facilities/{id}`) ================================================================================ # FILE: /okf/schemas/FacilityListEnvelope.md ================================================================================ --- type: Schema title: FacilityListEnvelope description: A page of the workspace's facilities, with the paging envelope. resource: https://opendpp-node.eu/openapi.json#/components/schemas/FacilityListEnvelope tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A page of the workspace's facilities, with the paging envelope. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `count` | integer | yes | Number of items returned in THIS page (≤ limit). | | `facilities` | array<[FacilityRow](/schemas/FacilityRow.md)> | yes | All facilities in the workspace, sorted by createdAt descending. | | `page` | integer | yes | 1-based page number returned. | | `limit` | integer | yes | Effective page size (default 100, max 200). | | `total` | integer | yes | Total items matching across all pages. | | `totalPages` | integer | yes | Total number of pages (≥ 1). | ## JSON Schema ```json { "description": "A page of the workspace's facilities, with the paging envelope.", "type": "object", "required": [ "success", "count", "facilities", "page", "limit", "total", "totalPages" ], "properties": { "success": { "type": "boolean", "const": true }, "count": { "type": "integer", "description": "Number of items returned in THIS page (≤ `limit`)." }, "facilities": { "type": "array", "items": { "$ref": "#/components/schemas/FacilityRow" }, "description": "All facilities in the workspace, sorted by createdAt descending. Operator-scoped keys see only their operator's facilities." }, "page": { "type": "integer", "description": "1-based page number returned." }, "limit": { "type": "integer", "description": "Effective page size (default 100, max 200)." }, "total": { "type": "integer", "description": "Total items matching across all pages." }, "totalPages": { "type": "integer", "description": "Total number of pages (≥ 1)." } } } ``` ## Used by - [listFacilities](/operations/listFacilities.md) (`GET /api/v1/facilities`) ================================================================================ # FILE: /okf/schemas/FacilityRow.md ================================================================================ --- type: Schema title: FacilityRow description: A facility (GS1 GLN) master-data row, exactly as stored. resource: https://opendpp-node.eu/openapi.json#/components/schemas/FacilityRow tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A facility (GS1 GLN) master-data row, exactly as stored. Returned in full to the owning tenant. Public exposure in passport documents differs by format: the *JSON-LD* document exposes `id`, `gln`, `name`, `activity` and `country` of a linked facility; the *AAS* export emits only the GLN, name and country (`manufacturingFacilityGln`/`Name`/`Country`). `streetAddress`, `city` and `postalCode` are emitted only to the owning/bound tenant in both formats. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | yes | Facility id (UUID). | | `gln` | string | yes | GS1 Global Location Number — 13 digits with a valid GS1 modulo-10 check digit. | | `name` | string | yes | Facility display name (trimmed, non-empty). | | `activity` | string,null | yes | Free-text activity, e.g. "Cell assembly", "Final manufacturing", "Recycling". | | `streetAddress` | string,null | yes | Street address. | | `city` | string,null | yes | City. | | `postalCode` | string,null | yes | Postal code. | | `country` | string | yes | 2-letter ISO 3166-1 alpha-2 country code, stored uppercase. | | `operatorId` | string,null | yes | Id of the owning Economic Operator, or null for a tenant-level facility. | | `tenantId` | string | yes | Owning tenant workspace id. | | `createdAt` | string | yes | — | | `updatedAt` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "A facility (GS1 GLN) master-data row, exactly as stored. Returned in full to the owning tenant. Public exposure in passport documents differs by format: the *JSON-LD* document exposes `id`, `gln`, `name`, `activity` and `country` of a linked facility; the *AAS* export emits only the GLN, name and country (`manufacturingFacilityGln`/`Name`/`Country`). `streetAddress`, `city` and `postalCode` are emitted only to the owning/bound tenant in both formats.", "required": [ "id", "gln", "name", "activity", "streetAddress", "city", "postalCode", "country", "operatorId", "tenantId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Facility id (UUID)." }, "gln": { "type": "string", "pattern": "^[0-9]{13}$", "description": "GS1 Global Location Number — 13 digits with a valid GS1 modulo-10 check digit. Unique platform-wide. Immutable after registration (it is the resolvable UFI)." }, "name": { "type": "string", "description": "Facility display name (trimmed, non-empty)." }, "activity": { "type": [ "string", "null" ], "description": "Free-text activity, e.g. \"Cell assembly\", \"Final manufacturing\", \"Recycling\". Public in JSON-LD; not emitted in the AAS export." }, "streetAddress": { "type": [ "string", "null" ], "description": "Street address. Owner-only: redacted from public JSON-LD and never emitted in AAS." }, "city": { "type": [ "string", "null" ], "description": "City. Owner-only: redacted from public JSON-LD and never emitted in AAS." }, "postalCode": { "type": [ "string", "null" ], "description": "Postal code. Owner-only: redacted from public JSON-LD and never emitted in AAS." }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "2-letter ISO 3166-1 alpha-2 country code, stored uppercase. Public in both JSON-LD and AAS." }, "operatorId": { "type": [ "string", "null" ], "description": "Id of the owning Economic Operator, or null for a tenant-level facility. Set at creation; not updatable via PUT." }, "tenantId": { "type": "string", "description": "Owning tenant workspace id." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } ``` ## Used by - schema [FacilityCreatedEnvelope](/schemas/FacilityCreatedEnvelope.md) - schema [FacilityListEnvelope](/schemas/FacilityListEnvelope.md) - schema [FacilityEnvelope](/schemas/FacilityEnvelope.md) ================================================================================ # FILE: /okf/schemas/FacilityUpdateRequest.md ================================================================================ --- type: Schema title: FacilityUpdateRequest description: Partial update. resource: https://opendpp-node.eu/openapi.json#/components/schemas/FacilityUpdateRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Partial update. `gln` and `operatorId` are immutable — if present they are silently ignored, as is any unknown key. For `activity`/`streetAddress`/`city`/`postalCode` the *presence* of the key matters: the value is stringified and trimmed, and anything that trims to empty (null, "", or a whitespace-only string) clears the field to null — the same normalization as POST. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `name` | string | no | New name. | | `activity` | string,null | no | New activity, or null/"" to clear. | | `streetAddress` | string,null | no | New street address, or null/"" to clear. | | `city` | string,null | no | New city, or null/"" to clear. | | `postalCode` | string,null | no | New postal code, or null/"" to clear. | | `country` | string | no | New 2-letter ISO country code (400 if a string that does not match; stored uppercase; non-string values are silently ignored). | ## JSON Schema ```json { "type": "object", "description": "Partial update. `gln` and `operatorId` are immutable — if present they are silently ignored, as is any unknown key. For `activity`/`streetAddress`/`city`/`postalCode` the *presence* of the key matters: the value is stringified and trimmed, and anything that trims to empty (null, \"\", or a whitespace-only string) clears the field to null — the same normalization as POST.", "properties": { "name": { "type": "string", "minLength": 1, "description": "New name. Applied only when a non-empty string; empty/whitespace or non-string values are silently ignored (the name can never be cleared)." }, "activity": { "type": [ "string", "null" ], "description": "New activity, or null/\"\" to clear. A whitespace-only string is stored as \"\" (see schema description)." }, "streetAddress": { "type": [ "string", "null" ], "description": "New street address, or null/\"\" to clear. A whitespace-only string is stored as \"\" (see schema description)." }, "city": { "type": [ "string", "null" ], "description": "New city, or null/\"\" to clear. A whitespace-only string is stored as \"\" (see schema description)." }, "postalCode": { "type": [ "string", "null" ], "description": "New postal code, or null/\"\" to clear. A whitespace-only string is stored as \"\" (see schema description)." }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "New 2-letter ISO country code (400 if a string that does not match; stored uppercase; non-string values are silently ignored)." } } } ``` ## Used by - [updateFacility](/operations/updateFacility.md) (`PUT /api/v1/facilities/{id}`) ================================================================================ # FILE: /okf/schemas/ForwardedResolverError.md ================================================================================ --- type: Schema title: ForwardedResolverError description: Forwarded public-resolver body (no success field). resource: https://opendpp-node.eu/openapi.json#/components/schemas/ForwardedResolverError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Forwarded public-resolver body (no `success` field). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `error` | string | yes | — | | `message` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "Forwarded public-resolver body (no `success` field).", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } ``` ## Used by - schema [PassportGetNotFound](/schemas/PassportGetNotFound.md) ================================================================================ # FILE: /okf/schemas/ForwardedResolverRateLimitError.md ================================================================================ --- type: Schema title: ForwardedResolverRateLimitError description: Forwarded public-resolver limiter body (no success field, no headers). resource: https://opendpp-node.eu/openapi.json#/components/schemas/ForwardedResolverRateLimitError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Forwarded public-resolver limiter body (no `success` field, no headers). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `error` | string | yes | — | | `message` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "Forwarded public-resolver limiter body (no `success` field, no headers).", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } ``` ## Used by - schema [PassportGetTooManyRequests](/schemas/PassportGetTooManyRequests.md) ================================================================================ # FILE: /okf/schemas/GlobalRateLimitError.md ================================================================================ --- type: Schema title: GlobalRateLimitError description: Global rate-limit plugin default body (with x-ratelimit-* headers). resource: https://opendpp-node.eu/openapi.json#/components/schemas/GlobalRateLimitError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Global rate-limit plugin default body (with x-ratelimit-* headers). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `statusCode` | integer | yes | — | | `error` | string | yes | — | | `message` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "Global rate-limit plugin default body (with x-ratelimit-* headers).", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } ``` ## Used by - schema [PassportGetTooManyRequests](/schemas/PassportGetTooManyRequests.md) ================================================================================ # FILE: /okf/schemas/GrantDecisionResponse.md ================================================================================ --- type: Schema title: GrantDecisionResponse description: "Returned by deny and revoke: the updated grant, no token." resource: https://opendpp-node.eu/openapi.json#/components/schemas/GrantDecisionResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Returned by deny and revoke: the updated grant, no token. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `grant` | [GrantRow](/schemas/GrantRow.md) | yes | — | ## JSON Schema ```json { "type": "object", "description": "Returned by deny and revoke: the updated grant, no token.", "required": [ "success", "grant" ], "properties": { "success": { "type": "boolean", "const": true }, "grant": { "$ref": "#/components/schemas/GrantRow" } } } ``` ## Used by - [denyGrantRequest](/operations/denyGrantRequest.md) (`POST /api/v1/grants/{id}/deny`) - [revokeGrant](/operations/revokeGrant.md) (`DELETE /api/v1/grants/{id}`) ================================================================================ # FILE: /okf/schemas/GrantIssuedResponse.md ================================================================================ --- type: Schema title: GrantIssuedResponse description: Returned by direct issuance (201) and request approval (200). resource: https://opendpp-node.eu/openapi.json#/components/schemas/GrantIssuedResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Returned by direct issuance (201) and request approval (200). `token` is the raw capability token — shown ONCE here (and, on approval, in the grantee's inspection-link e-mail); only its SHA-256 hash is persisted. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `grant` | [GrantRow](/schemas/GrantRow.md) | yes | — | | `token` | string | yes | Legitimate-interest capability token (dpp_li_ + 32 lowercase hex). | ## JSON Schema ```json { "type": "object", "description": "Returned by direct issuance (201) and request approval (200). `token` is the raw capability token — shown ONCE here (and, on approval, in the grantee's inspection-link e-mail); only its SHA-256 hash is persisted.", "required": [ "success", "grant", "token" ], "properties": { "success": { "type": "boolean", "const": true }, "grant": { "$ref": "#/components/schemas/GrantRow" }, "token": { "type": "string", "pattern": "^dpp_li_[0-9a-f]{32}$", "description": "Legitimate-interest capability token (`dpp_li_` + 32 lowercase hex). Present it to public resolution endpoints as `Authorization: Bearer ` or `?grant=`. Treat like a password — it cannot be retrieved again." } } } ``` ## Used by - [createGrant](/operations/createGrant.md) (`POST /api/v1/grants`) - [approveGrantRequest](/operations/approveGrantRequest.md) (`POST /api/v1/grants/{id}/approve`) ================================================================================ # FILE: /okf/schemas/GrantListResponse.md ================================================================================ --- type: Schema title: GrantListResponse description: List envelope for GET /api/v1/grants (paginated). resource: https://opendpp-node.eu/openapi.json#/components/schemas/GrantListResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- List envelope for `GET /api/v1/grants` (paginated). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `count` | integer | yes | Number of items returned in THIS page (≤ limit). | | `page` | integer | yes | 1-based page number returned. | | `limit` | integer | yes | Effective page size (default 100, max 200). | | `total` | integer | yes | Total items matching across all pages. | | `totalPages` | integer | yes | Total number of pages (≥ 1). | | `grants` | array<[GrantRow](/schemas/GrantRow.md)> | yes | Grants for this page (≤ limit), ordered by status ascending then createdAt descending. | ## JSON Schema ```json { "type": "object", "description": "List envelope for `GET /api/v1/grants` (paginated).", "required": [ "success", "grants", "count", "page", "limit", "total", "totalPages" ], "properties": { "success": { "type": "boolean", "const": true }, "count": { "type": "integer", "description": "Number of items returned in THIS page (≤ `limit`)." }, "page": { "type": "integer", "description": "1-based page number returned." }, "limit": { "type": "integer", "description": "Effective page size (default 100, max 200)." }, "total": { "type": "integer", "description": "Total items matching across all pages." }, "totalPages": { "type": "integer", "description": "Total number of pages (≥ 1)." }, "grants": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/GrantRow" }, "description": "Grants for this page (≤ `limit`), ordered by `status` ascending then `createdAt` descending." } } } ``` ## Used by - [listGrants](/operations/listGrants.md) (`GET /api/v1/grants`) ================================================================================ # FILE: /okf/schemas/GrantRevokeForbidden.md ================================================================================ --- type: Schema title: GrantRevokeForbidden description: "The two 403 bodies of grant revocation: the route-level {error, message} body (an AUTHORITY grant cannot be revoked by the workspace; no success field) and the standard middleware envelope." resource: https://opendpp-node.eu/openapi.json#/components/schemas/GrantRevokeForbidden tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The two 403 bodies of grant revocation: the route-level `{error, message}` body (an `AUTHORITY` grant cannot be revoked by the workspace; no `success` field) and the standard middleware envelope. ## JSON Schema ```json { "description": "The two 403 bodies of grant revocation: the route-level `{error, message}` body (an `AUTHORITY` grant cannot be revoked by the workspace; no `success` field) and the standard middleware envelope.", "anyOf": [ { "$ref": "#/components/schemas/GrantRouteError" }, { "$ref": "#/components/schemas/Error" } ] } ``` ## Used by - [revokeGrant](/operations/revokeGrant.md) (`DELETE /api/v1/grants/{id}`) ================================================================================ # FILE: /okf/schemas/GrantRouteError.md ================================================================================ --- type: Schema title: GrantRouteError description: Error body used by the grants endpoints' route-level errors (400/403/404/409). resource: https://opendpp-node.eu/openapi.json#/components/schemas/GrantRouteError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Error body used by the grants endpoints' route-level errors (400/403/404/409). Unlike the standard error envelope, it has NO `success` field. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `error` | string | yes | HTTP reason phrase, e.g. Bad Request, Not Found, Conflict, Forbidden. | | `message` | string | yes | Human-readable explanation. | ## JSON Schema ```json { "type": "object", "description": "Error body used by the grants endpoints' route-level errors (400/403/404/409). Unlike the standard error envelope, it has NO `success` field.", "required": [ "error", "message" ], "not": { "required": [ "success" ] }, "properties": { "error": { "type": "string", "description": "HTTP reason phrase, e.g. `Bad Request`, `Not Found`, `Conflict`, `Forbidden`." }, "message": { "type": "string", "description": "Human-readable explanation." } } } ``` ## Used by - [createGrant](/operations/createGrant.md) (`POST /api/v1/grants`) - [approveGrantRequest](/operations/approveGrantRequest.md) (`POST /api/v1/grants/{id}/approve`) - [denyGrantRequest](/operations/denyGrantRequest.md) (`POST /api/v1/grants/{id}/deny`) - [revokeGrant](/operations/revokeGrant.md) (`DELETE /api/v1/grants/{id}`) - schema [GrantRevokeForbidden](/schemas/GrantRevokeForbidden.md) ================================================================================ # FILE: /okf/schemas/GrantRow.md ================================================================================ --- type: Schema title: GrantRow description: Tenant-facing projection of an access grant. resource: https://opendpp-node.eu/openapi.json#/components/schemas/GrantRow tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Tenant-facing projection of an access grant. The token hash, issuer user id, revoking actor and request IP are never exposed; raw capability tokens appear only in the one-time issuance/approval responses. All fields are always present (nullable ones serialize as `null`). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | yes | — | | `status` | string | yes | PENDING = undecided third-party request (no token exists yet); ACTIVE = usable token; DENIED = rejected request; REVOKED = soft-revoked. | | `kind` | string | yes | LEGITIMATE_INTEREST (dpp_li_… tokens, tenant-issued or approved from a request) or AUTHORITY (dpp_auth_… tokens, platform-issued for market surveillance; not t… | | `granteeName` | string | yes | — | | `granteeEmail` | string,null | yes | — | | `organization` | string,null | yes | — | | `purpose` | string,null | yes | The stated legitimate interest. | | `scopeType` | string | yes | What the token unlocks on the public resolvers: a single battery unit, a single passport, or the whole workspace. | | `passportId` | string,null | yes | Set for PASSPORT scope, and also for UNIT scope (the unit's parent passport). | | `batteryUnitId` | string,null | yes | Set only for UNIT scope. | | `issuerType` | string | yes | TENANT = issued directly via this API; REQUEST = submitted by a third party through the hosted request-access page; PLATFORM = platform-admin-issued (AUTHORITY… | | `issuerEmail` | string,null | yes | E-mail of the issuing user; null when issued by an API key or created from a public request. | | `decidedAt` | string,null | yes | When a PENDING request was approved/denied; null for direct issuances. | | `decidedBy` | string,null | yes | The deciding actor: a user e-mail, API_KEY_ when decided via an API key, or the literal unknown in degenerate authentication states. | | `expiresAt` | string | yes | Hard expiry; the public resolvers reject the token after this instant. | | `revokedAt` | string,null | yes | — | | `lastUsedAt` | string,null | yes | Last successful use on a public resolver (book-kept best-effort). | | `useCount` | integer | yes | Successful public-resolver uses (incremented best-effort). | | `createdAt` | string | yes | — | | `revocable` | boolean | yes | Computed: false for AUTHORITY grants (platform-managed), true otherwise. | ## JSON Schema ```json { "type": "object", "description": "Tenant-facing projection of an access grant. The token hash, issuer user id, revoking actor and request IP are never exposed; raw capability tokens appear only in the one-time issuance/approval responses. All fields are always present (nullable ones serialize as `null`).", "required": [ "id", "status", "kind", "granteeName", "granteeEmail", "organization", "purpose", "scopeType", "passportId", "batteryUnitId", "issuerType", "issuerEmail", "decidedAt", "decidedBy", "expiresAt", "revokedAt", "lastUsedAt", "useCount", "createdAt", "revocable" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "DENIED", "REVOKED" ], "description": "`PENDING` = undecided third-party request (no token exists yet); `ACTIVE` = usable token; `DENIED` = rejected request; `REVOKED` = soft-revoked." }, "kind": { "type": "string", "enum": [ "LEGITIMATE_INTEREST", "AUTHORITY" ], "description": "`LEGITIMATE_INTEREST` (`dpp_li_…` tokens, tenant-issued or approved from a request) or `AUTHORITY` (`dpp_auth_…` tokens, platform-issued for market surveillance; not tenant-revocable)." }, "granteeName": { "type": "string", "maxLength": 160 }, "granteeEmail": { "type": [ "string", "null" ], "maxLength": 254 }, "organization": { "type": [ "string", "null" ], "maxLength": 200 }, "purpose": { "type": [ "string", "null" ], "maxLength": 2000, "description": "The stated legitimate interest." }, "scopeType": { "type": "string", "enum": [ "UNIT", "PASSPORT", "TENANT" ], "description": "What the token unlocks on the public resolvers: a single battery unit, a single passport, or the whole workspace." }, "passportId": { "type": [ "string", "null" ], "description": "Set for `PASSPORT` scope, and also for `UNIT` scope (the unit's parent passport). `null` for `TENANT` scope." }, "batteryUnitId": { "type": [ "string", "null" ], "description": "Set only for `UNIT` scope." }, "issuerType": { "type": "string", "enum": [ "TENANT", "PLATFORM", "REQUEST" ], "description": "`TENANT` = issued directly via this API; `REQUEST` = submitted by a third party through the hosted request-access page; `PLATFORM` = platform-admin-issued (AUTHORITY grants)." }, "issuerEmail": { "type": [ "string", "null" ], "description": "E-mail of the issuing user; `null` when issued by an API key or created from a public request." }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When a PENDING request was approved/denied; `null` for direct issuances." }, "decidedBy": { "type": [ "string", "null" ], "description": "The deciding actor: a user e-mail, `API_KEY_` when decided via an API key, or the literal `unknown` in degenerate authentication states." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Hard expiry; the public resolvers reject the token after this instant. PENDING requests carry a provisional 90-day expiry that is replaced on approval." }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful use on a public resolver (book-kept best-effort)." }, "useCount": { "type": "integer", "description": "Successful public-resolver uses (incremented best-effort)." }, "createdAt": { "type": "string", "format": "date-time" }, "revocable": { "type": "boolean", "description": "Computed: `false` for `AUTHORITY` grants (platform-managed), `true` otherwise." } } } ``` ## Used by - schema [GrantListResponse](/schemas/GrantListResponse.md) - schema [GrantIssuedResponse](/schemas/GrantIssuedResponse.md) - schema [GrantDecisionResponse](/schemas/GrantDecisionResponse.md) ================================================================================ # FILE: /okf/schemas/Gs1BatchDecodeError.md ================================================================================ --- type: Schema title: Gs1BatchDecodeError description: A per-item decode failure — the batch itself still returns 200 (partial-success). resource: https://opendpp-node.eu/openapi.json#/components/schemas/Gs1BatchDecodeError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A per-item decode failure — the batch itself still returns 200 (partial-success). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `ok` | boolean | yes | — | | `error` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "A per-item decode failure — the batch itself still returns 200 (partial-success).", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" } } } ``` ## Used by - schema [Gs1BatchDecodeResult](/schemas/Gs1BatchDecodeResult.md) ================================================================================ # FILE: /okf/schemas/Gs1BatchDecodeOk.md ================================================================================ --- type: Schema title: Gs1BatchDecodeOk description: A successfully decoded item — the same fields as the single-scan 200 minus success. resource: https://opendpp-node.eu/openapi.json#/components/schemas/Gs1BatchDecodeOk tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A successfully decoded item — the same fields as the single-scan 200 minus `success`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `ok` | boolean | yes | — | | `input` | string | yes | — | | `elementString` | string,null | yes | — | | `hri` | array | yes | — | | `canonicalUpi` | string,null | yes | — | | `digitalLinkUri` | string,null | yes | — | | `ai` | object | yes | — | ## JSON Schema ```json { "type": "object", "description": "A successfully decoded item — the same fields as the single-scan 200 minus `success`.", "required": [ "ok", "input", "elementString", "hri", "canonicalUpi", "digitalLinkUri", "ai" ], "properties": { "ok": { "type": "boolean", "const": true }, "input": { "type": "string" }, "elementString": { "type": [ "string", "null" ] }, "hri": { "type": "array", "items": { "type": "string" } }, "canonicalUpi": { "type": [ "string", "null" ] }, "digitalLinkUri": { "type": [ "string", "null" ] }, "ai": { "type": "object", "additionalProperties": { "type": "string" } } } } ``` ## Used by - schema [Gs1BatchDecodeResult](/schemas/Gs1BatchDecodeResult.md) ================================================================================ # FILE: /okf/schemas/Gs1BatchDecodeResult.md ================================================================================ --- type: Schema title: Gs1BatchDecodeResult description: "One batch-decode result, aligned to its input item: a decoded scan (ok: true) or a per-item error (ok: false + error)." resource: https://opendpp-node.eu/openapi.json#/components/schemas/Gs1BatchDecodeResult tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One batch-decode result, aligned to its input item: a decoded scan (`ok: true`) or a per-item error (`ok: false` + `error`). `ok` is the discriminant. ## JSON Schema ```json { "description": "One batch-decode result, aligned to its input item: a decoded scan (`ok: true`) or a per-item error (`ok: false` + `error`). `ok` is the discriminant.", "oneOf": [ { "$ref": "#/components/schemas/Gs1BatchDecodeOk" }, { "$ref": "#/components/schemas/Gs1BatchDecodeError" } ] } ``` ## Used by - [decodeGs1Batch](/operations/decodeGs1Batch.md) (`POST /api/v1/gs1/decode/batch`) ================================================================================ # FILE: /okf/schemas/HealthStatus.md ================================================================================ --- type: Schema title: HealthStatus description: Health-check body of GET /health. resource: https://opendpp-node.eu/openapi.json#/components/schemas/HealthStatus tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Health-check body of `GET /health`. Carries the running build identity (`apiVersion`/`commit`/`builtAt`) in addition to the liveness fields. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `status` | string | yes | — | | `service` | string | yes | — | | `timestamp` | string | yes | Current server time, ISO 8601 UTC with milliseconds. | | `apiVersion` | string | yes | SemVer of the public API contract currently served (equals the OpenAPI document's info.version; its MAJOR equals the /api/v1 URL major). | | `commit` | string | yes | Short git commit SHA of the running build, or "unknown" when a build did not inject it. | | `builtAt` | string | yes | Build/deploy timestamp (ISO 8601 UTC), or "unknown" when a build did not inject it. | ## JSON Schema ```json { "type": "object", "description": "Health-check body of `GET /health`. Carries the running build identity (`apiVersion`/`commit`/`builtAt`) in addition to the liveness fields.", "required": [ "status", "service", "timestamp", "apiVersion", "commit", "builtAt" ], "properties": { "status": { "type": "string", "const": "OK" }, "service": { "type": "string", "const": "OpenDPP B2B Enterprise Engine" }, "timestamp": { "type": "string", "format": "date-time", "description": "Current server time, ISO 8601 UTC with milliseconds." }, "apiVersion": { "type": "string", "description": "SemVer of the public API contract currently served (equals the OpenAPI document's `info.version`; its MAJOR equals the `/api/v1` URL major).", "examples": [ "1.0.0" ] }, "commit": { "type": "string", "description": "Short git commit SHA of the running build, or `\"unknown\"` when a build did not inject it.", "examples": [ "a7a96d0", "unknown" ] }, "builtAt": { "type": "string", "description": "Build/deploy timestamp (ISO 8601 UTC), or `\"unknown\"` when a build did not inject it.", "examples": [ "2026-06-12T09:30:00Z", "unknown" ] } } } ``` ## Used by - [getHealth](/operations/getHealth.md) (`GET /health`) ================================================================================ # FILE: /okf/schemas/MaterialVocabularyListResponse.md ================================================================================ --- type: Schema title: MaterialVocabularyListResponse description: Envelope of GET /api/v1/materials. resource: https://opendpp-node.eu/openapi.json#/components/schemas/MaterialVocabularyListResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Envelope of `GET /api/v1/materials`. Caveat: unlike most authenticated endpoints there is NO `success` field. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `materials` | array<[MaterialVocabularyRow](/schemas/MaterialVocabularyRow.md)> | yes | Active vocabulary entries, ordered by kind ascending then name ascending, capped at limit (max 1000). | ## JSON Schema ```json { "type": "object", "description": "Envelope of `GET /api/v1/materials`. Caveat: unlike most authenticated endpoints there is NO `success` field.", "required": [ "materials" ], "properties": { "materials": { "type": "array", "description": "Active vocabulary entries, ordered by `kind` ascending then `name` ascending, capped at `limit` (max 1000).", "items": { "$ref": "#/components/schemas/MaterialVocabularyRow" } } } } ``` ## Used by - [listMaterials](/operations/listMaterials.md) (`GET /api/v1/materials`) ================================================================================ # FILE: /okf/schemas/MaterialVocabularyRow.md ================================================================================ --- type: Schema title: MaterialVocabularyRow description: One entry of the platform-curated material vocabulary. resource: https://opendpp-node.eu/openapi.json#/components/schemas/MaterialVocabularyRow tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One entry of the platform-curated material vocabulary. Entries are unique per (`kind`, `name`). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | yes | — | | `name` | string | yes | Canonical display name, e.g. "Organic Cotton" or "Lithium Iron Phosphate (LFP)". | | `kind` | string | yes | Vocabulary kind. | | `casNumber` | string,null | yes | Optional CAS registry number (chemicals/substances); null when not applicable. | | `description` | string,null | yes | Optional short note shown in the picker; null when unset. | ## JSON Schema ```json { "type": "object", "description": "One entry of the platform-curated material vocabulary. Entries are unique per (`kind`, `name`).", "required": [ "id", "name", "kind", "casNumber", "description" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Canonical display name, e.g. \"Organic Cotton\" or \"Lithium Iron Phosphate (LFP)\"." }, "kind": { "type": "string", "enum": [ "material", "fiber", "chemistry", "substance", "hazard", "crm" ], "description": "Vocabulary kind. `crm` = critical raw material." }, "casNumber": { "type": [ "string", "null" ], "description": "Optional CAS registry number (chemicals/substances); null when not applicable." }, "description": { "type": [ "string", "null" ], "description": "Optional short note shown in the picker; null when unset." } } } ``` ## Used by - schema [MaterialVocabularyListResponse](/schemas/MaterialVocabularyListResponse.md) ================================================================================ # FILE: /okf/schemas/MerkleTreeAttestationProof.md ================================================================================ --- type: Schema title: MerkleTreeAttestationProof description: "OpenDPP's own proof type — an ADVANCED electronic seal: an ECDSA prime256v1 signature over a SHA-256 Merkle root of the key-sorted metadata (one leaf per top-level metadata key)." resource: https://opendpp-node.eu/openapi.json#/components/schemas/MerkleTreeAttestationProof tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- OpenDPP's own proof type — an ADVANCED electronic seal: an ECDSA prime256v1 signature over a SHA-256 Merkle root of the key-sorted metadata (one leaf per top-level metadata key). Deliberately NOT a W3C DataIntegrityProof / `ecdsa-jcs-2019` Verifiable Credential (no RFC 8785 JCS canonicalization). Verifiable offline: rebuild the Merkle root from `metadata` — substituting each `redactedLeaves` hash for its placeholder-masked key, and EXCLUDING any placeholder-masked key that has no `redactedLeaves` entry (such a key was never present in the sealed metadata; the serializer injects the owner-only placeholder unconditionally) — then verify `signatureValue` with `publicKeyPem`; the `x5c` chain validates against the platform seal CA (`GET /.well-known/opendpp-seal-ca.pem`) and the `rfc3161` token via `openssl ts -verify`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@type` | array | yes | Always ["MerkleTreeAttestationProof"]. | | `type` | string | yes | — | | `signatureAlgorithm` | string | yes | — | | `created` | string | yes | Mirrors the passport's updatedAt. | | `proofPurpose` | string | yes | — | | `verificationMethod` | string | yes | https://opendpp-node.eu/passport/{passportId}#key-1. | | `signatureValue` | string | yes | Base64 ECDSA P-256/SHA-256 signature over the hex Merkle root string (same value as the document's digitalSeal). | | `publicKeyPem` | string | yes | PEM public key for verification (same value as the document's signingPublicKey). | | `x5c` | array | no | OPTIONAL (omitted when no chain was recorded at seal time). | | `rfc3161` | object | no | OPTIONAL (omitted when timestamping was off/unavailable at seal time). | | `merkleRoot` | string | yes | Hex SHA-256 Merkle root over the key-sorted metadata leaves. | | `redactedLeaves` | object | no | OPTIONAL — present only when at least one masked key actually exists in the underlying sealed metadata. | ## JSON Schema ```json { "type": "object", "description": "OpenDPP's own proof type — an ADVANCED electronic seal: an ECDSA prime256v1 signature over a SHA-256 Merkle root of the key-sorted metadata (one leaf per top-level metadata key). Deliberately NOT a W3C DataIntegrityProof / `ecdsa-jcs-2019` Verifiable Credential (no RFC 8785 JCS canonicalization). Verifiable offline: rebuild the Merkle root from `metadata` — substituting each `redactedLeaves` hash for its placeholder-masked key, and EXCLUDING any placeholder-masked key that has no `redactedLeaves` entry (such a key was never present in the sealed metadata; the serializer injects the owner-only placeholder unconditionally) — then verify `signatureValue` with `publicKeyPem`; the `x5c` chain validates against the platform seal CA (`GET /.well-known/opendpp-seal-ca.pem`) and the `rfc3161` token via `openssl ts -verify`.", "required": [ "@type", "type", "signatureAlgorithm", "created", "proofPurpose", "verificationMethod", "signatureValue", "publicKeyPem", "merkleRoot" ], "properties": { "@type": { "type": "array", "items": { "type": "string", "const": "MerkleTreeAttestationProof" }, "description": "Always `[\"MerkleTreeAttestationProof\"]`." }, "type": { "type": "string", "const": "MerkleTreeAttestationProof" }, "signatureAlgorithm": { "type": "string", "const": "ECDSA-P256-SHA256-over-MerkleRoot" }, "created": { "type": "string", "format": "date-time", "description": "Mirrors the passport's `updatedAt`." }, "proofPurpose": { "type": "string", "const": "assertionMethod" }, "verificationMethod": { "type": "string", "format": "uri", "description": "`https://opendpp-node.eu/passport/{passportId}#key-1`." }, "signatureValue": { "type": "string", "description": "Base64 ECDSA P-256/SHA-256 signature over the hex Merkle root string (same value as the document's `digitalSeal`)." }, "publicKeyPem": { "type": "string", "description": "PEM public key for verification (same value as the document's `signingPublicKey`)." }, "x5c": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL (omitted when no chain was recorded at seal time). X.509 chain as base64 DER (no PEM armor), leaf first, binding the signing key to the tenant's legal identity; issued by the platform seal CA. Denormalised at seal time, so later key/cert rotations never retroactively change a proof." }, "rfc3161": { "type": "object", "description": "OPTIONAL (omitted when timestamping was off/unavailable at seal time). RFC 3161 trusted timestamp over SHA-256(merkleRoot) — an independent existed-at anchor from the configured TSA.", "required": [ "genTime", "token" ], "properties": { "genTime": { "type": [ "string", "null" ], "format": "date-time", "description": "TSA generation time." }, "token": { "type": "string", "description": "Base64 DER RFC 3161 TimeStampToken; verifies offline via `openssl ts -verify`." } } }, "merkleRoot": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hex SHA-256 Merkle root over the key-sorted metadata leaves." }, "redactedLeaves": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "OPTIONAL — present only when at least one masked key actually exists in the underlying sealed metadata. Maps each such metadata key to its TRUE hex leaf hash, so the Merkle root can be reconstructed from the redacted document. A masked key that was never present in the metadata (the owner-only key is placeholder-injected unconditionally for non-owner tiers) yields NO entry here — verifiers must exclude placeholder-valued keys without an entry when rebuilding the tree." } } } ``` ## Used by - schema [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) ================================================================================ # FILE: /okf/schemas/OperatorGetResponse.md ================================================================================ --- type: Schema title: OperatorGetResponse description: A single economic operator record. resource: https://opendpp-node.eu/openapi.json#/components/schemas/OperatorGetResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A single economic operator record. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `operator` | [OperatorRow](/schemas/OperatorRow.md) | yes | — | ## JSON Schema ```json { "description": "A single economic operator record.", "type": "object", "required": [ "success", "operator" ], "properties": { "success": { "type": "boolean", "const": true }, "operator": { "$ref": "#/components/schemas/OperatorRow" } } } ``` ## Used by - [getOperator](/operations/getOperator.md) (`GET /api/v1/operators/{id}`) ================================================================================ # FILE: /okf/schemas/OperatorListResponse.md ================================================================================ --- type: Schema title: OperatorListResponse description: The economic operators bound to the calling workspace. resource: https://opendpp-node.eu/openapi.json#/components/schemas/OperatorListResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The economic operators bound to the calling workspace. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `count` | integer | yes | Number of operators returned (the list is not paginated). | | `operators` | array<[OperatorRow](/schemas/OperatorRow.md)> | yes | — | ## JSON Schema ```json { "description": "The economic operators bound to the calling workspace.", "type": "object", "required": [ "success", "count", "operators" ], "properties": { "success": { "type": "boolean", "const": true }, "count": { "type": "integer", "description": "Number of operators returned (the list is not paginated)." }, "operators": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorRow" } } } } ``` ## Used by - [listOperators](/operations/listOperators.md) (`GET /api/v1/operators`) ================================================================================ # FILE: /okf/schemas/OperatorMinimalError.md ================================================================================ --- type: Schema title: OperatorMinimalError description: Minimal error envelope used by the operator/key self-service handlers — note the standard error key is ABSENT (unlike the shared Error schema). resource: https://opendpp-node.eu/openapi.json#/components/schemas/OperatorMinimalError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Minimal error envelope used by the operator/key self-service handlers — note the standard `error` key is ABSENT (unlike the shared Error schema). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "Minimal error envelope used by the operator/key self-service handlers — note the standard `error` key is ABSENT (unlike the shared Error schema).", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "const": false }, "message": { "type": "string" } } } ``` ## Used by - [deleteOperator](/operations/deleteOperator.md) (`DELETE /api/v1/operators/{id}`) - schema [OperatorMinimalErrorResponse](/schemas/OperatorMinimalErrorResponse.md) - the shared error responses ================================================================================ # FILE: /okf/schemas/OperatorMinimalErrorResponse.md ================================================================================ --- type: Schema title: OperatorMinimalErrorResponse description: "An operator-endpoint error: either the route's minimal {error, message} body (no success field) or the standard middleware envelope." resource: https://opendpp-node.eu/openapi.json#/components/schemas/OperatorMinimalErrorResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- An operator-endpoint error: either the route's minimal `{error, message}` body (no `success` field) or the standard middleware envelope. ## JSON Schema ```json { "description": "An operator-endpoint error: either the route's minimal `{error, message}` body (no `success` field) or the standard middleware envelope.", "anyOf": [ { "$ref": "#/components/schemas/OperatorMinimalError" }, { "$ref": "#/components/schemas/Error" } ] } ``` ## Used by - [registerOperator](/operations/registerOperator.md) (`POST /api/v1/operators`) - [rotateTenantKeys](/operations/rotateTenantKeys.md) (`POST /api/v1/tenants/rotate-keys`) ================================================================================ # FILE: /okf/schemas/OperatorRow.md ================================================================================ --- type: Schema title: OperatorRow description: An economic-operator record (EconomicOperator). resource: https://opendpp-node.eu/openapi.json#/components/schemas/OperatorRow tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- An economic-operator record (`EconomicOperator`). Operators are scoped to your workspace (each workspace keeps its own row for a given `regId`). Returned verbatim from the database (no field stripping); nullable fields are serialized as `null`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | yes | Operator UUID. | | `name` | string | yes | Legal/display name of the operator. | | `regId` | string | yes | Official registration id (EORI number, VAT id, DUNS, or national business-registry id). | | `regIdScheme` | string,null | yes | Which kind of registration id regId is. | | `role` | string | yes | Supply-chain role, free text — e.g. "MANUFACTURER", "IMPORTER", "RETAILER". | | `archivedAt` | string,null | yes | Soft-delete / cessation-of-trading marker. | | `createdAt` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "An economic-operator record (`EconomicOperator`). Operators are scoped to your workspace (each workspace keeps its own row for a given `regId`). Returned verbatim from the database (no field stripping); nullable fields are serialized as `null`.", "required": [ "id", "name", "regId", "regIdScheme", "role", "archivedAt", "createdAt" ], "properties": { "id": { "type": "string", "description": "Operator UUID." }, "name": { "type": "string", "description": "Legal/display name of the operator." }, "regId": { "type": "string", "description": "Official registration id (EORI number, VAT id, DUNS, or national business-registry id). Unique within your workspace and immutable after registration." }, "regIdScheme": { "type": [ "string", "null" ], "enum": [ "EORI", "VAT", "DUNS", "NATIONAL", "OTHER", null ], "description": "Which kind of registration id `regId` is. `null` = unspecified national/business id. When `EORI`, `regId` is guaranteed to satisfy the EORI syntax `^[A-Z]{2}[A-Za-z0-9]{1,15}$`." }, "role": { "type": "string", "description": "Supply-chain role, free text — e.g. `\"MANUFACTURER\"`, `\"IMPORTER\"`, `\"RETAILER\"`. Defaults to `\"MANUFACTURER\"` at registration." }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete / cessation-of-trading marker. Non-null = the operator is archived (its passports are retained and still publicly resolvable)." }, "createdAt": { "type": "string", "format": "date-time" } } } ``` ## Used by - schema [RegisterOperatorResponse](/schemas/RegisterOperatorResponse.md) - schema [UpdateOperatorResponse](/schemas/UpdateOperatorResponse.md) - schema [OperatorListResponse](/schemas/OperatorListResponse.md) - schema [OperatorGetResponse](/schemas/OperatorGetResponse.md) ================================================================================ # FILE: /okf/schemas/PassportAasEnvironment.md ================================================================================ --- type: Schema title: PassportAasEnvironment description: IDTA Asset Administration Shell environment (returned when Accept contains application/aas+json), role-filtered for the caller's access tier. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportAasEnvironment tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- IDTA Asset Administration Shell environment (returned when `Accept` contains `application/aas+json`), role-filtered for the caller's access tier. Identifiers use `urn:opendpp:*` forms: the shell id is `urn:opendpp:aas:` with idShort `AAS_` and `globalAssetId` `urn:opendpp:asset::` (plus `specificAssetIds` carrying the productId and, when a facility is assigned, its GLN). The environment contains, at minimum, a `GeneralProductInformation` submodel (`urn:opendpp:submodel:general:`) and a `ComplianceMetadata` submodel (`urn:opendpp:submodel:compliance`); for a manufacturer/product-identified passport it also carries an IDTA Digital Nameplate submodel (idShort `Nameplate`) and one or more additive per-category submodel views (ESPR-category views such as CarbonFootprint / TechnicalData, id prefix `urn:opendpp:submodel:category:`). An `eidasVerificationSeal` submodel is appended when the tenant has signing keys configured. Loose schema — the full AAS document structure is documented with the public resolution endpoints. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `assetAdministrationShells` | array | yes | — | | `submodels` | array | yes | — | | `conceptDescriptions` | array | yes | — | ## JSON Schema ```json { "type": "object", "description": "IDTA Asset Administration Shell environment (returned when `Accept` contains `application/aas+json`), role-filtered for the caller's access tier. Identifiers use `urn:opendpp:*` forms: the shell id is `urn:opendpp:aas:` with idShort `AAS_` and `globalAssetId` `urn:opendpp:asset::` (plus `specificAssetIds` carrying the productId and, when a facility is assigned, its GLN). The environment contains, at minimum, a `GeneralProductInformation` submodel (`urn:opendpp:submodel:general:`) and a `ComplianceMetadata` submodel (`urn:opendpp:submodel:compliance`); for a manufacturer/product-identified passport it also carries an IDTA Digital Nameplate submodel (idShort `Nameplate`) and one or more additive per-category submodel views (ESPR-category views such as CarbonFootprint / TechnicalData, id prefix `urn:opendpp:submodel:category:`). An `eidasVerificationSeal` submodel is appended when the tenant has signing keys configured. Loose schema — the full AAS document structure is documented with the public resolution endpoints.", "required": [ "assetAdministrationShells", "submodels", "conceptDescriptions" ], "properties": { "assetAdministrationShells": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "submodels": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "conceptDescriptions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } ``` ## Used by - [getPassport](/operations/getPassport.md) (`GET /api/v1/passports/{id}`) ================================================================================ # FILE: /okf/schemas/PassportBulkBadRequest.md ================================================================================ --- type: Schema title: PassportBulkBadRequest description: "The 400 bodies of bulk ingestion: every row failed (Bulk Ingestion Failed), or the request never reached row processing and returns the default request-rejection body." resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportBulkBadRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The 400 bodies of bulk ingestion: every row failed (`Bulk Ingestion Failed`), or the request never reached row processing and returns the default request-rejection body. ## JSON Schema ```json { "description": "The 400 bodies of bulk ingestion: every row failed (`Bulk Ingestion Failed`), or the request never reached row processing and returns the default request-rejection body.", "oneOf": [ { "$ref": "#/components/schemas/PassportBulkFailure" }, { "$ref": "#/components/schemas/DefaultRequestRejectionError" } ] } ``` ## Used by - [bulkIngestPassports](/operations/bulkIngestPassports.md) (`POST /api/v1/passports/bulk`) ================================================================================ # FILE: /okf/schemas/PassportBulkFailure.md ================================================================================ --- type: Schema title: PassportBulkFailure description: 400 body of POST /api/v1/passports/bulk when EVERY row failed. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportBulkFailure tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 400 body of `POST /api/v1/passports/bulk` when EVERY row failed. Note: `errors` is an array of STRINGS (not objects) and there is NO `message` field. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `error` | string | yes | — | | `errors` | array | yes | One human-readable string per failed row, prefixed [SKU: ] where the productId was readable. | ## JSON Schema ```json { "type": "object", "required": [ "success", "error", "errors" ], "description": "400 body of `POST /api/v1/passports/bulk` when EVERY row failed. Note: `errors` is an array of STRINGS (not objects) and there is NO `message` field.", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "Bulk Ingestion Failed" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "One human-readable string per failed row, prefixed `[SKU: ]` where the productId was readable." } } } ``` ## Used by - schema [PassportBulkBadRequest](/schemas/PassportBulkBadRequest.md) ================================================================================ # FILE: /okf/schemas/PassportBulkRequest.md ================================================================================ --- type: Schema title: PassportBulkRequest description: A batch of passports to ingest, with optional dry-run preview and upsert-on-conflict behaviour. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportBulkRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A batch of passports to ingest, with optional dry-run preview and upsert-on-conflict behaviour. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `passports` | array<[PassportBulkRow](/schemas/PassportBulkRow.md)> | yes | 1–200 rows. | | `dryRun` | boolean | no | When true, every row is validated and the duplicate/operator/facility checks run, but nothing is written — the response is 200 and reports which rows are OK (r… | | `upsert` | boolean | no | When true, a row whose (productId, operator) already exists updates the existing passport instead of being reported as a duplicate (a sealed passport is never… | ## JSON Schema ```json { "description": "A batch of passports to ingest, with optional dry-run preview and upsert-on-conflict behaviour.", "type": "object", "required": [ "passports" ], "properties": { "passports": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/PassportBulkRow" }, "description": "1–200 rows. The bounds are enforced before any row is processed; violations return the default `{statusCode, code, error, message}` error body." }, "dryRun": { "type": "boolean", "description": "When `true`, every row is validated and the duplicate/operator/facility checks run, but **nothing is written** — the response is **200** and reports which rows are OK (`results`) vs failed (`errors[]`). Powers a pre-import preview." }, "upsert": { "type": "boolean", "description": "When `true`, a row whose `(productId, operator)` already exists **updates** the existing passport instead of being reported as a duplicate (a sealed passport is never overwritten). Enables idempotent re-import of a corrected catalog." } } } ``` ## Used by - [bulkIngestPassports](/operations/bulkIngestPassports.md) (`POST /api/v1/passports/bulk`) ================================================================================ # FILE: /okf/schemas/PassportBulkResult.md ================================================================================ --- type: Schema title: PassportBulkResult description: 201 partial-success envelope of POST /api/v1/passports/bulk. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportBulkResult tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 201 partial-success envelope of `POST /api/v1/passports/bulk`. Returned whenever at least one row was inserted, even if other rows failed. Each result row carries a `vcReady` UNTP Verifiable-Credential readiness signal and a per-row non-blocking `warnings[]` (non-GS1 advisory + PII-shape privacy advisory; empty when the row is clean). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | Template: "Bulk CSV ingestion finished. | | `insertedCount` | integer | yes | Number of rows actually inserted (= results.length). | | `results` | array | yes | — | | `errors` | array | no | Human-readable per-row failure strings, prefixed [SKU: ] (or "Missing or invalid productId in spreadsheet row"). | ## JSON Schema ```json { "type": "object", "required": [ "success", "message", "insertedCount", "results" ], "description": "201 partial-success envelope of `POST /api/v1/passports/bulk`. Returned whenever at least one row was inserted, even if other rows failed. Each result row carries a `vcReady` UNTP Verifiable-Credential readiness signal and a per-row non-blocking `warnings[]` (non-GS1 advisory + PII-shape privacy advisory; empty when the row is clean).", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "Template: \"Bulk CSV ingestion finished. Registered passports, skipped rows with errors.\"" }, "insertedCount": { "type": "integer", "minimum": 0, "description": "Number of rows actually inserted (= `results.length`)." }, "results": { "type": "array", "items": { "type": "object", "required": [ "productId", "digitalLinkUri", "vcReady" ], "properties": { "productId": { "type": "string" }, "digitalLinkUri": { "type": "string", "format": "uri", "description": "Generated GS1 Digital Link URI `https://opendpp-node.eu/{01|8003}/{productId}`." }, "vcReady": { "type": "boolean", "description": "Whether this row's passport can emit a UNTP Verifiable Credential — true only when a manufacturing facility with a country of production is linked. On a `dryRun` preview this reflects the EFFECTIVE facility after import (the row's facility, else the existing passport's preserved one)." }, "vcReadyReason": { "type": [ "string", "null" ], "description": "Null when `vcReady` is true; otherwise a short, actionable reason (link a facility with a country of production)." }, "warnings": { "type": "array", "description": "Per-row non-blocking advisories — the non-GS1 \"no scannable QR\" note and the PII-shape privacy advisory. Empty `[]` when the row is clean; never blocks the row.", "items": { "$ref": "#/components/schemas/AdvisoryItem" } } } } }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Human-readable per-row failure strings, prefixed `[SKU: ]` (or \"Missing or invalid productId in spreadsheet row\"). Present ONLY when at least one row failed — omitted otherwise." } } } ``` ## Used by - [bulkIngestPassports](/operations/bulkIngestPassports.md) (`POST /api/v1/passports/bulk`) ================================================================================ # FILE: /okf/schemas/PassportBulkRow.md ================================================================================ --- type: Schema title: PassportBulkRow description: One bulk-ingestion row. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportBulkRow tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One bulk-ingestion row. The HTTP layer only requires each row to be an object; rows missing `productId` or `metadata`, failing ESPR validation, referencing unbound operators/unknown facilities, or duplicating an existing `(productId, operatorId)` pair are SKIPPED and reported as strings in the response `errors[]` — they never fail the whole request (unless every row fails). Bulk rows do not support `draft` or `enrichment`, are always created with `status: "ACTIVE"`, and do NOT get `metadata.gtin`/`metadata.grai` auto-injected. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `productId` | string | no | GTIN-14 / GRAI / free-form SKU (required in practice; rows without it are skipped with an error string). | | `operatorId` | string | no | Optional EconomicOperator UUID bound to your workspace; defaults to the workspace's first bound operator. | | `facilityId` | string | no | Optional Facility UUID in your workspace; unknown ids skip the row. | | `metadata` | [PassportMetadataInput](/schemas/PassportMetadataInput.md) | no | — | ## JSON Schema ```json { "type": "object", "description": "One bulk-ingestion row. The HTTP layer only requires each row to be an object; rows missing `productId` or `metadata`, failing ESPR validation, referencing unbound operators/unknown facilities, or duplicating an existing `(productId, operatorId)` pair are SKIPPED and reported as strings in the response `errors[]` — they never fail the whole request (unless every row fails). Bulk rows do not support `draft` or `enrichment`, are always created with `status: \"ACTIVE\"`, and do NOT get `metadata.gtin`/`metadata.grai` auto-injected.", "properties": { "productId": { "type": "string", "description": "GTIN-14 / GRAI / free-form SKU (required in practice; rows without it are skipped with an error string)." }, "operatorId": { "type": "string", "description": "Optional EconomicOperator UUID bound to your workspace; defaults to the workspace's first bound operator. Operator-scoped API keys force their operator." }, "facilityId": { "type": "string", "description": "Optional Facility UUID in your workspace; unknown ids skip the row." }, "metadata": { "$ref": "#/components/schemas/PassportMetadataInput" } }, "additionalProperties": true } ``` ## Used by - schema [PassportBulkRequest](/schemas/PassportBulkRequest.md) ================================================================================ # FILE: /okf/schemas/PassportCreateBadRequest.md ================================================================================ --- type: Schema title: PassportCreateBadRequest description: "The 400 bodies of passport creation: an ESPR validation failure with per-field errors[], or the standard error triple / pre-handler rejection." resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportCreateBadRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The 400 bodies of passport creation: an ESPR validation failure with per-field `errors[]`, or the standard error triple / pre-handler rejection. ## JSON Schema ```json { "description": "The 400 bodies of passport creation: an ESPR validation failure with per-field `errors[]`, or the standard error triple / pre-handler rejection.", "anyOf": [ { "$ref": "#/components/schemas/PassportCreateValidationError" }, { "$ref": "#/components/schemas/Error" } ] } ``` ## Used by - [createPassport](/operations/createPassport.md) (`POST /api/v1/passports`) ================================================================================ # FILE: /okf/schemas/PassportCreateRequest.md ================================================================================ --- type: Schema title: PassportCreateRequest description: "A passport to create: its product identifier and ESPR category metadata, with optional operator and facility binding, a draft flag, and enrichment held outside the sealed metadata." resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportCreateRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A passport to create: its product identifier and ESPR category metadata, with optional operator and facility binding, a draft flag, and enrichment held outside the sealed metadata. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `productId` | string | yes | Product identifier: a GTIN-14 (exactly 14 digits with a valid GS1 mod-10 check digit — auto-copied to metadata.gtin), a GRAI (14-digit numeric asset id with va… | | `operatorId` | string | no | UUID of an EconomicOperator bound to your tenant workspace (403 if not bound). | | `facilityId` | string | no | Optional UUID of a Facility (GLN-backed Unique Facility Identifier) in your workspace; 400 if not found. | | `metadata` | [PassportMetadataInput](/schemas/PassportMetadataInput.md) | yes | — | | `draft` | boolean | no | When true: skips ALL ESPR validation, stores the passport with status: "DRAFT" (not publicly resolvable), and emits no webhook. | | `enrichment` | [PassportEnrichmentInput](/schemas/PassportEnrichmentInput.md) | no | — | ## JSON Schema ```json { "description": "A passport to create: its product identifier and ESPR category metadata, with optional operator and facility binding, a draft flag, and enrichment held outside the sealed metadata.", "type": "object", "required": [ "productId", "metadata" ], "properties": { "productId": { "type": "string", "minLength": 1, "description": "Product identifier: a GTIN-14 (exactly 14 digits with a valid GS1 mod-10 check digit — auto-copied to `metadata.gtin`), a GRAI (14-digit numeric asset id with valid check digit + optional up to 16 alphanumeric serial chars, total 14–30 — auto-copied to `metadata.grai`), or a free-form SKU. Determines the GS1 Application Identifier (`01` vs `8003`) in the generated Digital Link URI. Whitespace-only values are rejected 400. Unique per economic operator (409 on duplicate)." }, "operatorId": { "type": "string", "description": "UUID of an EconomicOperator bound to your tenant workspace (403 if not bound). Defaults to your workspace's first bound operator. Operator-scoped API keys force their own operator (403 on mismatch)." }, "facilityId": { "type": "string", "description": "Optional UUID of a Facility (GLN-backed Unique Facility Identifier) in your workspace; 400 if not found." }, "metadata": { "$ref": "#/components/schemas/PassportMetadataInput" }, "draft": { "type": "boolean", "default": false, "description": "When true: skips ALL ESPR validation, stores the passport with `status: \"DRAFT\"` (not publicly resolvable), and emits no webhook. Publish later via a validated edit." }, "enrichment": { "$ref": "#/components/schemas/PassportEnrichmentInput" } } } ``` ## Used by - [createPassport](/operations/createPassport.md) (`POST /api/v1/passports`) ================================================================================ # FILE: /okf/schemas/PassportCreateValidationError.md ================================================================================ --- type: Schema title: ESPR validation failure description: ESPR validation failure resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportCreateValidationError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `error` | string | yes | — | | `message` | string | yes | — | | `errors` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | yes | Blocking findings. | | `warnings` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | no | Omitted entirely when there are no warnings. | ## JSON Schema ```json { "type": "object", "title": "ESPR validation failure", "required": [ "success", "error", "message", "errors" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "Validation Failed" }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Blocking findings. Items produced by the category-validity check (`metadata.category` missing/unknown) carry no `friendlyMessage`." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Omitted entirely when there are no warnings." } } } ``` ## Used by - schema [PassportCreateBadRequest](/schemas/PassportCreateBadRequest.md) ================================================================================ # FILE: /okf/schemas/PassportEnrichmentInput.md ================================================================================ --- type: Schema title: PassportEnrichmentInput description: Optional presentational (non-regulatory) marketing enrichment, stored OUTSIDE the ESPR-validated metadata and the Merkle seal; it never appears in the JSON-LD passport document. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportEnrichmentInput tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Optional presentational (non-regulatory) marketing enrichment, stored OUTSIDE the ESPR-validated metadata and the Merkle seal; it never appears in the JSON-LD passport document. Server-side it is whitelist-sanitized rather than rejected: unknown keys are dropped; `tagline` is trimmed and capped at 200 chars, `description` at 4000, image `caption` at 200, link `label` at 120; at most 24 `images` and 24 `links` are kept; URLs must be http, https, or mailto (any other scheme, e.g. `javascript:` or `data:`, is silently dropped). An enrichment that sanitizes down to nothing is stored as null. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `tagline` | string | no | Short marketing tagline (server-capped at 200 chars). | | `description` | string | no | Marketing description (server-capped at 4000 chars). | | `images` | array | no | Up to 24 kept. | | `links` | array | no | Up to 24 kept. | ## JSON Schema ```json { "type": "object", "description": "Optional presentational (non-regulatory) marketing enrichment, stored OUTSIDE the ESPR-validated metadata and the Merkle seal; it never appears in the JSON-LD passport document. Server-side it is whitelist-sanitized rather than rejected: unknown keys are dropped; `tagline` is trimmed and capped at 200 chars, `description` at 4000, image `caption` at 200, link `label` at 120; at most 24 `images` and 24 `links` are kept; URLs must be http, https, or mailto (any other scheme, e.g. `javascript:` or `data:`, is silently dropped). An enrichment that sanitizes down to nothing is stored as null.", "properties": { "tagline": { "type": "string", "description": "Short marketing tagline (server-capped at 200 chars)." }, "description": { "type": "string", "description": "Marketing description (server-capped at 4000 chars)." }, "images": { "type": "array", "description": "Up to 24 kept. Items without a valid http/https/mailto `url` are dropped.", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "http, https, or mailto only." }, "caption": { "type": "string", "description": "Server-capped at 200 chars." } } } }, "links": { "type": "array", "description": "Up to 24 kept. Items without a valid http/https/mailto `url` are dropped; a missing `label` defaults to the URL.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Server-capped at 120 chars." }, "url": { "type": "string", "format": "uri", "description": "http, https, or mailto only." } } } } }, "additionalProperties": true } ``` ## Used by - schema [PassportCreateRequest](/schemas/PassportCreateRequest.md) - schema [PassportUpdateRequest](/schemas/PassportUpdateRequest.md) ================================================================================ # FILE: /okf/schemas/PassportGetNotFound.md ================================================================================ --- type: Schema title: PassportGetNotFound description: "The two 404 bodies of an authenticated passport read: the standard workspace-scoped envelope, or the body forwarded from the public resolver (no success field)." resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportGetNotFound tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The two 404 bodies of an authenticated passport read: the standard workspace-scoped envelope, or the body forwarded from the public resolver (no `success` field). ## JSON Schema ```json { "description": "The two 404 bodies of an authenticated passport read: the standard workspace-scoped envelope, or the body forwarded from the public resolver (no `success` field).", "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ForwardedResolverError" } ] } ``` ## Used by - [getPassport](/operations/getPassport.md) (`GET /api/v1/passports/{id}`) ================================================================================ # FILE: /okf/schemas/PassportGetTooManyRequests.md ================================================================================ --- type: Schema title: PassportGetTooManyRequests description: "The two 429 bodies of an authenticated passport read: the global limiter's default body (with x-ratelimit-* headers), or the body forwarded from the inner public resolver's limiter (no headers)." resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportGetTooManyRequests tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The two 429 bodies of an authenticated passport read: the global limiter's default body (with `x-ratelimit-*` headers), or the body forwarded from the inner public resolver's limiter (no headers). ## JSON Schema ```json { "description": "The two 429 bodies of an authenticated passport read: the global limiter's default body (with `x-ratelimit-*` headers), or the body forwarded from the inner public resolver's limiter (no headers).", "anyOf": [ { "$ref": "#/components/schemas/GlobalRateLimitError" }, { "$ref": "#/components/schemas/ForwardedResolverRateLimitError" } ] } ``` ## Used by - [getPassport](/operations/getPassport.md) (`GET /api/v1/passports/{id}`) ================================================================================ # FILE: /okf/schemas/PassportIngestCreated.md ================================================================================ --- type: Schema title: PassportIngestCreated description: 201 envelope of POST /api/v1/passports. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportIngestCreated tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 201 envelope of `POST /api/v1/passports`. `passport` is the public redacted JSON-LD; `warnings`/`notices` are always present (possibly empty); `vcReady`/`vcReadyReason` report UNTP Verifiable-Credential readiness. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | "Digital Product Passport successfully validated and ingested", or "Draft passport saved" when draft: true. | | `passport` | [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) | yes | The PUBLIC redacted JSON-LD passport document (unsealed at creation: digitalSeal/proof are null). | | `warnings` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | yes | Non-blocking findings — a MIX of ESPR validation warnings (no code) and machine-coded advisories (a stable code, e.g. NON_GS1_PRODUCT_ID, PII_SHAPE_DETECTED). | | `notices` | array<[AdvisoryItem](/schemas/AdvisoryItem.md)> | yes | Informational advisories about helpful things the API did (always coded): OPERATOR_AUTO_ATTRIBUTED (operatorId omitted → the workspace's sole bound operator us… | | `vcReady` | boolean | no | Whether this passport can emit a UNTP Verifiable Credential — true only when a manufacturing facility with a country of production is linked (producedAtFacilit… | | `vcReadyReason` | string,null | no | Null when vcReady is true; otherwise a short, actionable reason (link a facility with a country of production). | ## JSON Schema ```json { "type": "object", "required": [ "success", "message", "passport", "warnings", "notices" ], "description": "201 envelope of `POST /api/v1/passports`. `passport` is the public redacted JSON-LD; `warnings`/`notices` are always present (possibly empty); `vcReady`/`vcReadyReason` report UNTP Verifiable-Credential readiness.", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "\"Digital Product Passport successfully validated and ingested\", or \"Draft passport saved\" when `draft: true`." }, "passport": { "$ref": "#/components/schemas/PublicPassportJsonLd", "description": "The PUBLIC redacted JSON-LD passport document (unsealed at creation: `digitalSeal`/`proof` are null). The owner-only metadata key `facilityDetails` is always replaced with the literal string \"[REDACTED - Privileged Access Required]\" — even in this creator-facing echo, and even when the submitted metadata did not contain it. For `category: \"batteries\"`, the restricted legitimate-interest keys `detailedPerformance`, `lifecycleAndInUse`, and `circularityAndDisassembly` are masked the same way when present." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Non-blocking findings — a MIX of ESPR validation warnings (no `code`) and machine-coded advisories (a stable `code`, e.g. `NON_GS1_PRODUCT_ID`, `PII_SHAPE_DETECTED`). Always present; empty for drafts. See `AdvisoryItem` for the coded shape." }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/AdvisoryItem" }, "description": "Informational advisories about helpful things the API did (always coded): `OPERATOR_AUTO_ATTRIBUTED` (operatorId omitted → the workspace's sole bound operator used), `GTIN_AUTO_COPIED` (a valid GTIN/GRAI copied into metadata.gtin/grai). Always present; empty when nothing to note." }, "vcReady": { "type": "boolean", "description": "Whether this passport can emit a UNTP Verifiable Credential — true only when a manufacturing facility with a country of production is linked (`producedAtFacility` + `countryOfProduction` are required by the UNTP DPP schema; a GLN is optional). The passport still publishes and resolves as AAS / JSON-LD / HTML regardless." }, "vcReadyReason": { "type": [ "string", "null" ], "description": "Null when `vcReady` is true; otherwise a short, actionable reason (link a facility with a country of production)." } } } ``` ## Used by - [createPassport](/operations/createPassport.md) (`POST /api/v1/passports`) ================================================================================ # FILE: /okf/schemas/PassportListItem.md ================================================================================ --- type: Schema title: PassportListItem description: One JSON-LD passport document as it appears in GET /api/v1/passports list responses. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportListItem tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One JSON-LD passport document as it appears in `GET /api/v1/passports` list responses. Same shape as `PublicPassportJsonLd` with list-specific divergences imposed by the route's declared response serialization: `economicOperator` never carries `role`; `manufacturingFacility` is always `null`; the `@context` term map (second array element) is emptied to `{}`; and `proof` is emptied to `{}` on sealed items (`null` on unsealed) — fetch the single passport for the verifiable proof block. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | array<—> | yes | Exactly two entries: the context URL https://opendpp-node.eu/contexts/dpp/v1 and an inline term map covering the 9 fixed DPP terms (DigitalProductPassport, eco… | | `@type` | string | yes | — | | `@id` | string | yes | The passport's canonical GS1 Digital Link URI (same value as digitalLinkUri). | | `id` | string | yes | Server-assigned passport UUID. | | `productId` | string | yes | Caller-supplied product identifier: a GTIN-14 (^[0-9]{14}$ with valid GS1 modulo-10 check digit), a GRAI (^[0-9]{14}[A-Za-z0-9]{0,16}$), or a free-form SKU. | | `digitalLinkUri` | string | yes | SKU/type-level GS1 Digital Link URI: {origin}/{01|8003}/{productId} (AI-21 carries the passport UUID at SKU level; individual units carry their physical serial… | | `digitalSeal` | string,null | yes | ADVANCED electronic seal: base64 ECDSA prime256v1 (P-256) signature over the Merkle root of the key-sorted metadata. | | `signingPublicKey` | string,null | yes | PEM public key that verifies digitalSeal. | | `status` | string | yes | Passport lifecycle status (serialized as ACTIVE when unset). | | `archivedAt` | string,null | yes | Soft-delete marker (owner off-boarded / decommissioned). | | `retentionUntil` | string,null | yes | Minimum-availability deadline; the passport is never purged before this instant. | | `proof` | — | yes | {} when sealed, null when unsealed. | | `createdAt` | string | yes | — | | `updatedAt` | string | yes | — | | `economicOperator` | — | yes | The economic operator (manufacturer/importer/retailer) responsible for the product. | | `manufacturingFacility` | null | yes | Always null in list responses (facility nodes are only embedded on single-passport reads). | | `metadata` | object | yes | The ESPR category metadata, tier-masked: keys above the caller's tier hold the literal string [REDACTED - Privileged Access Required] instead of their value. | ## JSON Schema ```json { "type": "object", "description": "One JSON-LD passport document as it appears in `GET /api/v1/passports` list responses. Same shape as `PublicPassportJsonLd` with list-specific divergences imposed by the route's declared response serialization: `economicOperator` never carries `role`; `manufacturingFacility` is always `null`; the `@context` term map (second array element) is emptied to `{}`; and `proof` is emptied to `{}` on sealed items (`null` on unsealed) — fetch the single passport for the verifiable proof block.", "additionalProperties": true, "required": [ "@context", "@type", "@id", "id", "productId", "digitalLinkUri", "digitalSeal", "signingPublicKey", "status", "archivedAt", "retentionUntil", "proof", "createdAt", "updatedAt", "economicOperator", "manufacturingFacility", "metadata" ], "properties": { "@context": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": "Exactly two entries: the context URL `https://opendpp-node.eu/contexts/dpp/v1` and an inline term map covering the 9 fixed DPP terms (`DigitalProductPassport`, `economicOperator`, `manufacturingFacility`, `metadata`, `digitalSeal`, `signingPublicKey`, `status`, `archivedAt`, `retentionUntil`) plus one generated term per metadata key (`https://opendpp-node.eu/contexts/dpp/v1#`)." }, "@type": { "type": "string", "const": "DigitalProductPassport" }, "@id": { "type": "string", "format": "uri", "description": "The passport's canonical GS1 Digital Link URI (same value as `digitalLinkUri`)." }, "id": { "type": "string", "description": "Server-assigned passport UUID." }, "productId": { "type": "string", "description": "Caller-supplied product identifier: a GTIN-14 (`^[0-9]{14}$` with valid GS1 modulo-10 check digit), a GRAI (`^[0-9]{14}[A-Za-z0-9]{0,16}$`), or a free-form SKU." }, "digitalLinkUri": { "type": "string", "format": "uri", "description": "SKU/type-level GS1 Digital Link URI: `{origin}/{01|8003}/{productId}` (AI-21 carries the passport UUID at SKU level; individual units carry their physical serial instead)." }, "digitalSeal": { "type": [ "string", "null" ], "description": "ADVANCED electronic seal: base64 ECDSA prime256v1 (P-256) signature over the Merkle root of the key-sorted metadata. `null` when the passport has not been sealed." }, "signingPublicKey": { "type": [ "string", "null" ], "description": "PEM public key that verifies `digitalSeal`. `null` when unsealed." }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "RECALLED", "DECOMMISSIONED" ], "description": "Passport lifecycle status (serialized as `ACTIVE` when unset). `DRAFT` is only ever visible to owner-tier callers — public/grant resolution of a draft returns 404." }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete marker (owner off-boarded / decommissioned). Archived passports remain publicly resolvable (ESPR persistence duty)." }, "retentionUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "Minimum-availability deadline; the passport is never purged before this instant." }, "proof": { "anyOf": [ { "type": "object", "additionalProperties": false, "description": "Always the empty object on sealed items — proof contents are stripped by the list serialization." }, { "type": "null" } ], "description": "`{}` when sealed, `null` when unsealed. The full `MerkleTreeAttestationProof` is only available on single-passport reads." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "economicOperator": { "anyOf": [ { "$ref": "#/components/schemas/EconomicOperatorNode" }, { "type": "null" } ], "description": "The economic operator (manufacturer/importer/retailer) responsible for the product. Public in all tiers." }, "manufacturingFacility": { "type": "null", "description": "Always `null` in list responses (facility nodes are only embedded on single-passport reads)." }, "metadata": { "type": "object", "additionalProperties": true, "description": "The ESPR category metadata, tier-masked: keys above the caller's tier hold the literal string `[REDACTED - Privileged Access Required]` instead of their value." } } } ``` ## Used by - schema [PassportListResponse](/schemas/PassportListResponse.md) ================================================================================ # FILE: /okf/schemas/PassportListResponse.md ================================================================================ --- type: Schema title: PassportListResponse description: Envelope of GET /api/v1/passports. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportListResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Envelope of GET /api/v1/passports. The response is serialized against a declared response schema: top-level keys other than these four are stripped. There is NO total count. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | Always true on 200. | | `page` | integer | yes | Effective page after server-side clamping (min 1). | | `limit` | integer | yes | Effective page size after server-side clamping (default 10, max 100). | | `passports` | array<[PassportListItem](/schemas/PassportListItem.md)> | yes | — | ## JSON Schema ```json { "type": "object", "description": "Envelope of GET /api/v1/passports. The response is serialized against a declared response schema: top-level keys other than these four are stripped. There is NO total count.", "required": [ "success", "page", "limit", "passports" ], "properties": { "success": { "type": "boolean", "description": "Always true on 200." }, "page": { "type": "integer", "minimum": 1, "description": "Effective page after server-side clamping (min 1)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Effective page size after server-side clamping (default 10, max 100)." }, "passports": { "type": "array", "items": { "$ref": "#/components/schemas/PassportListItem" } } } } ``` ## Used by - [listPassports](/operations/listPassports.md) (`GET /api/v1/passports`) ================================================================================ # FILE: /okf/schemas/PassportMetadataInput.md ================================================================================ --- type: Schema title: PassportMetadataInput description: The ESPR product metadata payload. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportMetadataInput tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The ESPR product metadata payload. For non-draft ingestion and for the validate-only endpoints, `category` is mandatory and must be one of the 9 ESPR categories; each category then mandates its own field set (e.g. textiles require `fiberComposition`, `careInstructions`, `size`; batteries require `batteryCategory`, `chemistry`, `electrochemicalCapacity`, `durability`, `recycledContentShare`, `carbonFootprint`). For five categories — textiles, batteries, electronics, chemicals, construction — the authoritative per-category JSON Schema (required fields, value constraints, field help) is served live at `GET /api/v1/schemas/{category}`; the other four (cosmetics, toys, iron-steel, aluminium) are validated by built-in server-side rules and `GET /api/v1/schemas/{category}` returns 404 for them. Cross-field rules are enforced on top: `materialComposition` (and textile `fiberComposition`) percentages must sum to 100 ±0.1, `originCountry` must be a real ISO 3166-1 alpha-2 code, textile hazardous-substance concentrations are checked against REACH ppm limits. A documented set of supplementary objects (e.g. `technicalProperties`, `environmentalFootprint`, `circularityAttributes`, `esgDueDiligence`, `detailedPerformance`) produce non-blocking `warnings` instead of `errors` when malformed. With `draft: true` (single ingestion only) validation is skipped entirely and any object is accepted. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `category` | string | no | ESPR product category; selects the validation rules. | | `originCountry` | string | no | ISO 3166-1 alpha-2 country code (validated against the full 249-code set). | | `commodityCode` | string | no | Optional HS / TARIC commodity code (4–10 digits). | ## JSON Schema ```json { "type": "object", "description": "The ESPR product metadata payload. For non-draft ingestion and for the validate-only endpoints, `category` is mandatory and must be one of the 9 ESPR categories; each category then mandates its own field set (e.g. textiles require `fiberComposition`, `careInstructions`, `size`; batteries require `batteryCategory`, `chemistry`, `electrochemicalCapacity`, `durability`, `recycledContentShare`, `carbonFootprint`). For five categories — textiles, batteries, electronics, chemicals, construction — the authoritative per-category JSON Schema (required fields, value constraints, field help) is served live at `GET /api/v1/schemas/{category}`; the other four (cosmetics, toys, iron-steel, aluminium) are validated by built-in server-side rules and `GET /api/v1/schemas/{category}` returns 404 for them. Cross-field rules are enforced on top: `materialComposition` (and textile `fiberComposition`) percentages must sum to 100 ±0.1, `originCountry` must be a real ISO 3166-1 alpha-2 code, textile hazardous-substance concentrations are checked against REACH ppm limits. A documented set of supplementary objects (e.g. `technicalProperties`, `environmentalFootprint`, `circularityAttributes`, `esgDueDiligence`, `detailedPerformance`) produce non-blocking `warnings` instead of `errors` when malformed. With `draft: true` (single ingestion only) validation is skipped entirely and any object is accepted.", "properties": { "category": { "type": "string", "enum": [ "textiles", "batteries", "electronics", "cosmetics", "toys", "iron-steel", "aluminium", "chemicals", "construction" ], "description": "ESPR product category; selects the validation rules. Required whenever validation runs (i.e. always, except `draft: true` single ingestion)." }, "originCountry": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code (validated against the full 249-code set)." }, "commodityCode": { "type": "string", "pattern": "^[0-9]{4,10}$", "description": "Optional HS / TARIC commodity code (4–10 digits). Validated for every category when present (a malformed code is a 400). Not category-mandated, but required to project the passport into the EU DPP registry pointer (ESPR Art. 13)." } }, "additionalProperties": true } ``` ## Used by - schema [PassportCreateRequest](/schemas/PassportCreateRequest.md) - schema [PassportValidateOnlyRequest](/schemas/PassportValidateOnlyRequest.md) - schema [PassportBulkRow](/schemas/PassportBulkRow.md) ================================================================================ # FILE: /okf/schemas/PassportQuotaError.md ================================================================================ --- type: Schema title: PassportQuotaError description: 402 body for a write blocked by billing. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportQuotaError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 402 body for a write blocked by billing. Always carries `error` + `message`. A block caused by the subscription tier's published-passport CAP additionally sets `code: "passport_quota_exceeded"` plus `quota` and `upgradeUrl`. A programmatic (API-key) write on a tier without API access sets `code: "api_access_required"` plus `upgradeUrl` instead. Clients distinguish each from a lapsed-subscription 402 (no `code`) and can prompt an upgrade. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | no | Always false when present. | | `error` | string | yes | Short error title. | | `message` | string | yes | Human-readable explanation. | | `code` | string | no | Machine-readable discriminator. | | `quota` | object | no | Present only on a passport_quota_exceeded block: current usage vs the tier cap. | | `upgradeUrl` | string | no | Where the workspace owner can upgrade the plan. | ## JSON Schema ```json { "type": "object", "description": "402 body for a write blocked by billing. Always carries `error` + `message`. A block caused by the subscription tier's published-passport CAP additionally sets `code: \"passport_quota_exceeded\"` plus `quota` and `upgradeUrl`. A programmatic (API-key) write on a tier without API access sets `code: \"api_access_required\"` plus `upgradeUrl` instead. Clients distinguish each from a lapsed-subscription 402 (no `code`) and can prompt an upgrade.", "required": [ "error", "message" ], "properties": { "success": { "type": "boolean", "description": "Always `false` when present." }, "error": { "type": "string", "description": "Short error title.", "examples": [ "Payment Required" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "code": { "type": "string", "description": "Machine-readable discriminator. `passport_quota_exceeded` = the tier's passport cap is reached; `api_access_required` = a programmatic (API-key) write was attempted on a tier without the API-access entitlement (use the dashboard session, or upgrade to a Growth+ plan); omitted for a lapsed-subscription 402.", "examples": [ "passport_quota_exceeded", "api_access_required" ] }, "quota": { "type": "object", "description": "Present only on a `passport_quota_exceeded` block: current usage vs the tier cap.", "properties": { "tier": { "type": "string", "description": "The workspace subscription tier." }, "activePassports": { "type": "integer", "description": "Active (non-draft, non-archived) passports, counted tenant-wide." }, "passportLimit": { "type": "integer", "description": "The tier's passport cap." } } }, "upgradeUrl": { "type": "string", "description": "Where the workspace owner can upgrade the plan." } } } ``` ## Used by - the shared error responses ================================================================================ # FILE: /okf/schemas/PassportSealResponse.md ================================================================================ --- type: Schema title: PassportSealResponse description: 200 envelope of POST /api/v1/passports/{id}/seal. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportSealResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 200 envelope of POST /api/v1/passports/{id}/seal. `digitalSeal` is duplicated inside `passport.digitalSeal` and `passport.proof.signatureValue`. The passport document is serialized at the PUBLIC redaction tier; masked keys keep their true leaf hashes in `proof.redactedLeaves`. Note: despite the message wording, this endpoint does not change the passport's `status`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | Always true on 200. | | `message` | string | yes | — | | `digitalSeal` | string | yes | Base64 ECDSA P-256 (prime256v1) SHA-256 signature over the metadata Merkle root (ADVANCED electronic seal — not a qualified seal, not a W3C DataIntegrityProof). | | `signingPublicKey` | string | yes | PEM-encoded public key of the tenant's signing key pair; verify the seal offline against proof.merkleRoot. | | `passport` | [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) | yes | — | | `warnings` | array<[AdvisoryItem](/schemas/AdvisoryItem.md)> | yes | Publish-time re-warning: a single non-GS1 advisory when the sealed passport's productId is not a GS1 GTIN/GRAI (it has no scannable Digital Link — mint a GTIN… | ## JSON Schema ```json { "type": "object", "description": "200 envelope of POST /api/v1/passports/{id}/seal. `digitalSeal` is duplicated inside `passport.digitalSeal` and `passport.proof.signatureValue`. The passport document is serialized at the PUBLIC redaction tier; masked keys keep their true leaf hashes in `proof.redactedLeaves`. Note: despite the message wording, this endpoint does not change the passport's `status`.", "required": [ "success", "message", "digitalSeal", "signingPublicKey", "passport", "warnings" ], "properties": { "success": { "type": "boolean", "description": "Always true on 200." }, "message": { "type": "string", "const": "Passport sealed with the tenant's eIDAS advanced electronic seal and published." }, "digitalSeal": { "type": "string", "description": "Base64 ECDSA P-256 (prime256v1) SHA-256 signature over the metadata Merkle root (ADVANCED electronic seal — not a qualified seal, not a W3C DataIntegrityProof)." }, "signingPublicKey": { "type": "string", "description": "PEM-encoded public key of the tenant's signing key pair; verify the seal offline against `proof.merkleRoot`." }, "passport": { "$ref": "#/components/schemas/PublicPassportJsonLd" }, "warnings": { "type": "array", "description": "Publish-time re-warning: a single non-GS1 advisory when the sealed passport's `productId` is not a GS1 GTIN/GRAI (it has no scannable Digital Link — mint a GTIN you own via `POST /api/v1/gs1/gtin`). Empty `[]` when the productId is GS1-keyed. Non-blocking.", "items": { "$ref": "#/components/schemas/AdvisoryItem" } } } } ``` ## Used by - [sealPassport](/operations/sealPassport.md) (`POST /api/v1/passports/{id}/seal`) ================================================================================ # FILE: /okf/schemas/PassportStatusUpdateRequest.md ================================================================================ --- type: Schema title: PassportStatusUpdateRequest description: Body of PUT /api/v1/passports/{id}/status. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportStatusUpdateRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Body of PUT /api/v1/passports/{id}/status. Only `status` is read; any other keys are ignored (there is no `reason` field). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `status` | string | yes | Target lifecycle state. | ## JSON Schema ```json { "type": "object", "description": "Body of PUT /api/v1/passports/{id}/status. Only `status` is read; any other keys are ignored (there is no `reason` field).", "required": [ "status" ], "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "RECALLED", "DECOMMISSIONED" ], "description": "Target lifecycle state. DECOMMISSIONED starts the retention clock (retentionUntil = now + the configured retention period, default 15 years); ACTIVE reactivates (clears retentionUntil and archivedAt); RECALLED marks the product recalled. DRAFT is not a valid target — drafts are published via PUT /api/v1/passports/{id}." } } } ``` ## Used by - [updatePassportStatus](/operations/updatePassportStatus.md) (`PUT /api/v1/passports/{id}/status`) ================================================================================ # FILE: /okf/schemas/PassportStatusUpdateResponse.md ================================================================================ --- type: Schema title: PassportStatusUpdateResponse description: 200 envelope of PUT /api/v1/passports/{id}/status. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportStatusUpdateResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 200 envelope of PUT /api/v1/passports/{id}/status. The passport document is serialized at the PUBLIC redaction tier. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | Always true on 200. | | `message` | string | yes | Passport status successfully updated to . | | `status` | string | yes | The passport's new lifecycle state. | | `passport` | [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) | yes | — | ## JSON Schema ```json { "type": "object", "description": "200 envelope of PUT /api/v1/passports/{id}/status. The passport document is serialized at the PUBLIC redaction tier.", "required": [ "success", "message", "status", "passport" ], "properties": { "success": { "type": "boolean", "description": "Always true on 200." }, "message": { "type": "string", "description": "`Passport status successfully updated to `." }, "status": { "type": "string", "enum": [ "ACTIVE", "RECALLED", "DECOMMISSIONED" ], "description": "The passport's new lifecycle state." }, "passport": { "$ref": "#/components/schemas/PublicPassportJsonLd" } } } ``` ## Used by - [updatePassportStatus](/operations/updatePassportStatus.md) (`PUT /api/v1/passports/{id}/status`) ================================================================================ # FILE: /okf/schemas/PassportUpdateBadRequest.md ================================================================================ --- type: Schema title: PassportUpdateBadRequest description: "The two 400 bodies of a passport update: the standard error triple, or an ESPR validation failure (which, unlike creation, carries NO warnings array)." resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportUpdateBadRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The two 400 bodies of a passport update: the standard error triple, or an ESPR validation failure (which, unlike creation, carries NO `warnings` array). ## JSON Schema ```json { "description": "The two 400 bodies of a passport update: the standard error triple, or an ESPR validation failure (which, unlike creation, carries NO `warnings` array).", "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/PassportUpdateValidationError" } ] } ``` ## Used by - [updatePassport](/operations/updatePassport.md) (`PUT /api/v1/passports/{id}`) ================================================================================ # FILE: /okf/schemas/PassportUpdateRequest.md ================================================================================ --- type: Schema title: PassportUpdateRequest description: Body of PUT /api/v1/passports/{id}. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportUpdateRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Body of PUT /api/v1/passports/{id}. Unknown keys are ignored. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `metadata` | object | yes | Full replacement ESPR metadata object. | | `draft` | boolean | no | true = save as draft: skips ESPR validation and forces status DRAFT (this also demotes an already-published passport back to DRAFT). | | `changeReason` | string | no | Free-text reason recorded on the version-history snapshot. | | `facilityId` | string,null | no | GLN-backed facility assignment. | | `enrichment` | — | no | Presentational marketing block stored OUTSIDE the ESPR-validated metadata and the Merkle seal. | ## JSON Schema ```json { "type": "object", "description": "Body of PUT /api/v1/passports/{id}. Unknown keys are ignored.", "required": [ "metadata" ], "additionalProperties": true, "properties": { "metadata": { "type": "object", "description": "Full replacement ESPR metadata object. `metadata.category` must be one of: textiles, batteries, electronics, cosmetics, toys, iron-steel, aluminium, chemicals, construction. Validated against the category's compliance rules unless `draft: true` (400 with `errors[]` on failure — no `warnings` on this route). A machine-readable JSON Schema is published at GET /api/v1/schemas/{category} for **textiles, batteries, electronics, chemicals and construction only** — cosmetics, toys, iron-steel and aluminium are validated by built-in rules and return 404 from that endpoint." }, "draft": { "type": "boolean", "default": false, "description": "true = save as draft: skips ESPR validation and forces status DRAFT (this also demotes an already-published passport back to DRAFT). false/absent = validated save; a DRAFT passport is published (status ACTIVE, emits the passport.ingested webhook)." }, "changeReason": { "type": "string", "description": "Free-text reason recorded on the version-history snapshot. Defaults to \"API Update\"." }, "facilityId": { "type": [ "string", "null" ], "description": "GLN-backed facility assignment. Omit to leave unchanged; null or \"\" detaches; a UUID attaches a facility that must be owned by your tenant (otherwise 400)." }, "enrichment": { "oneOf": [ { "$ref": "#/components/schemas/PassportEnrichmentInput" }, { "type": "null" } ], "description": "Presentational marketing block stored OUTSIDE the ESPR-validated metadata and the Merkle seal. Include the key (even null/{}) to overwrite; omit to leave unchanged. An empty result after sanitation clears the block." } } } ``` ## Used by - [updatePassport](/operations/updatePassport.md) (`PUT /api/v1/passports/{id}`) ================================================================================ # FILE: /okf/schemas/PassportUpdateResponse.md ================================================================================ --- type: Schema title: PassportUpdateResponse description: 200 envelope of PUT /api/v1/passports/{id}. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportUpdateResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 200 envelope of PUT /api/v1/passports/{id}. The passport document is serialized at the PUBLIC redaction tier (owner-only/restricted metadata keys masked) even for the owner. Also carries the `vcReady`/`vcReadyReason` UNTP readiness signal and a non-blocking `warnings[]`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | Always true on 200. | | `message` | string | yes | "Draft published" when a validated save promoted a DRAFT to ACTIVE; the longer message otherwise. | | `passport` | [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) | yes | — | | `warnings` | array<[AdvisoryItem](/schemas/AdvisoryItem.md)> | yes | Non-blocking advisories. | ## JSON Schema ```json { "type": "object", "description": "200 envelope of PUT /api/v1/passports/{id}. The passport document is serialized at the PUBLIC redaction tier (owner-only/restricted metadata keys masked) even for the owner. Also carries the `vcReady`/`vcReadyReason` UNTP readiness signal and a non-blocking `warnings[]`.", "required": [ "success", "message", "passport", "warnings" ], "properties": { "success": { "type": "boolean", "description": "Always true on 200." }, "message": { "type": "string", "enum": [ "Draft published", "Digital Product Passport successfully updated and history versioned" ], "description": "\"Draft published\" when a validated save promoted a DRAFT to ACTIVE; the longer message otherwise." }, "passport": { "$ref": "#/components/schemas/PublicPassportJsonLd" }, "warnings": { "type": "array", "description": "Non-blocking advisories. Carries a single note when saving with `\"draft\": true` DEMOTED an already-published (ACTIVE/RECALLED/DECOMMISSIONED) passport to DRAFT — it is then no longer publicly resolvable. Empty `[]` otherwise.", "items": { "$ref": "#/components/schemas/AdvisoryItem" } } } } ``` ## Used by - [updatePassport](/operations/updatePassport.md) (`PUT /api/v1/passports/{id}`) ================================================================================ # FILE: /okf/schemas/PassportUpdateValidationError.md ================================================================================ --- type: Schema title: PassportUpdateValidationError description: 400 ESPR validation failure body of PUT /api/v1/passports/{id}. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportUpdateValidationError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 400 ESPR validation failure body of PUT /api/v1/passports/{id}. DIVERGENCE from POST /api/v1/passports: there is never a `warnings` array on this route. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `error` | string | yes | — | | `message` | string | yes | — | | `errors` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | yes | Blocking validation errors. | ## JSON Schema ```json { "type": "object", "description": "400 ESPR validation failure body of PUT /api/v1/passports/{id}. DIVERGENCE from POST /api/v1/passports: there is never a `warnings` array on this route.", "required": [ "success", "error", "message", "errors" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "Validation Failed" }, "message": { "type": "string", "example": "Dynamic metadata payload failed ESPR category schema validation" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Blocking validation errors. `friendlyMessage` is localized via the `lang` query parameter / Accept-Language (default en)." } } } ``` ## Used by - schema [PassportUpdateBadRequest](/schemas/PassportUpdateBadRequest.md) ================================================================================ # FILE: /okf/schemas/PassportValidateOnlyError.md ================================================================================ --- type: Schema title: PassportValidateOnlyError description: 400 envelope of the validate-only endpoints. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportValidateOnlyError tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 400 envelope of the validate-only endpoints. Three variants: ESPR validation failure (`error: "Validation Failed"`, with `success`, `category`, `errors[]`, optional `warnings[]` — omitted when none; category-validity error items carry no `friendlyMessage`); whitespace-only `productId` (`error: "Bad Request"`, `category: "unknown"`, `errors: []`, no `warnings`); and structural request rejections (body-schema violations, malformed JSON), which return only `error` + `message`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | no | — | | `error` | string | yes | — | | `message` | string | yes | — | | `category` | string | no | metadata.category echo, or "unknown" for structural failures. | | `errors` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | no | — | | `warnings` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | no | Omitted when there are no warnings. | ## JSON Schema ```json { "type": "object", "required": [ "error", "message" ], "description": "400 envelope of the validate-only endpoints. Three variants: ESPR validation failure (`error: \"Validation Failed\"`, with `success`, `category`, `errors[]`, optional `warnings[]` — omitted when none; category-validity error items carry no `friendlyMessage`); whitespace-only `productId` (`error: \"Bad Request\"`, `category: \"unknown\"`, `errors: []`, no `warnings`); and structural request rejections (body-schema violations, malformed JSON), which return only `error` + `message`.", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "enum": [ "Bad Request", "Validation Failed" ] }, "message": { "type": "string" }, "category": { "type": "string", "description": "`metadata.category` echo, or \"unknown\" for structural failures." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Omitted when there are no warnings." } } } ``` ## Used by - [validatePassport](/operations/validatePassport.md) (`POST /api/v1/passports/validate-only`) - [validatePassportPublic](/operations/validatePassportPublic.md) (`POST /api/v1/passports/validate-only-public`) ================================================================================ # FILE: /okf/schemas/PassportValidateOnlyRequest.md ================================================================================ --- type: Schema title: PassportValidateOnlyRequest description: A metadata payload to validate against its ESPR category rules without persisting anything. resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportValidateOnlyRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A metadata payload to validate against its ESPR category rules without persisting anything. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `productId` | string | yes | Product identifier (GTIN-14 / GRAI / SKU). | | `operatorId` | string | no | Accepted by the body schema but IGNORED by the validate-only handlers. | | `metadata` | [PassportMetadataInput](/schemas/PassportMetadataInput.md) | yes | — | ## JSON Schema ```json { "description": "A metadata payload to validate against its ESPR category rules without persisting anything.", "type": "object", "required": [ "productId", "metadata" ], "properties": { "productId": { "type": "string", "minLength": 1, "description": "Product identifier (GTIN-14 / GRAI / SKU). Required and checked non-empty (whitespace-only → 400), but not otherwise used by the dry-run." }, "operatorId": { "type": "string", "description": "Accepted by the body schema but IGNORED by the validate-only handlers." }, "metadata": { "$ref": "#/components/schemas/PassportMetadataInput" } } } ``` ## Used by - [validatePassport](/operations/validatePassport.md) (`POST /api/v1/passports/validate-only`) - [validatePassportPublic](/operations/validatePassportPublic.md) (`POST /api/v1/passports/validate-only-public`) ================================================================================ # FILE: /okf/schemas/PassportValidateOnlyResult.md ================================================================================ --- type: Schema title: PassportValidateOnlyResult description: 200 envelope of the validate-only endpoints (only the declared keys are emitted). resource: https://opendpp-node.eu/openapi.json#/components/schemas/PassportValidateOnlyResult tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 200 envelope of the validate-only endpoints (only the declared keys are emitted). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | — | | `category` | string | yes | Echo of metadata.category (or "unknown" if absent). | | `errors` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | yes | Always an empty array on 200. | | `warnings` | array<[ValidationErrorItem](/schemas/ValidationErrorItem.md)> | no | Non-blocking findings (e.g. malformed supplementary objects like circularityAttributes). | ## JSON Schema ```json { "type": "object", "required": [ "success", "message", "category", "errors" ], "description": "200 envelope of the validate-only endpoints (only the declared keys are emitted).", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "example": "Passport metadata payload is valid against the ESPR category data schema" }, "category": { "type": "string", "description": "Echo of `metadata.category` (or \"unknown\" if absent)." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "maxItems": 0, "description": "Always an empty array on 200." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Non-blocking findings (e.g. malformed supplementary objects like `circularityAttributes`). The key is OMITTED entirely when there are no warnings — it is never an empty array." } } } ``` ## Used by - [validatePassport](/operations/validatePassport.md) (`POST /api/v1/passports/validate-only`) - [validatePassportPublic](/operations/validatePassportPublic.md) (`POST /api/v1/passports/validate-only-public`) ================================================================================ # FILE: /okf/schemas/PublicBatteryUnitJsonLd.md ================================================================================ --- type: Schema title: PublicBatteryUnitJsonLd description: Public JSON-LD document for one individual serialised battery unit (EU Battery Regulation). resource: https://opendpp-node.eu/openapi.json#/components/schemas/PublicBatteryUnitJsonLd tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Public JSON-LD document for one individual serialised battery unit (EU Battery Regulation). The listed required keys are always present. EXACTLY ONE of two tier-dependent groups is added: anonymous (public) responses carry `restrictedData` (Annex XIII(2)-(4) notice) and OMIT `currentState`/`dynamicData` entirely; owner/grant (privileged) responses carry `currentState` (latest measurement or `null`) and `dynamicData` (up to 500 events, newest first) and omit `restrictedData`. The embedded `ofModel` passport is masked by the caller's tier like `GET /passport/{id}`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | array<—> | yes | The context URL https://opendpp-node.eu/contexts/dpp/v1 plus a fixed inline term map for the battery-unit terms. | | `@type` | string | yes | — | | `@id` | string | yes | The unit's GS1 Digital Link URI (AI-21 = the real physical serial). | | `id` | string | yes | — | | `serialNumber` | string | yes | The physical battery serial (the real GS1 AI-21 value; unique within its SKU/type passport). | | `digitalLinkUri` | string | yes | — | | `status` | string | yes | Annex XIII battery-status vocabulary. | | `manufacturedAt` | string,null | yes | — | | `repurposedFrom` | — | yes | Lineage: the original unit this repurposed/remanufactured battery came from. | | `successorUnits` | array<[BatteryUnitLineageRef](/schemas/BatteryUnitLineageRef.md)> | yes | Units re-placed on the market under a new passport derived from this one (empty array when none). | | `ofModel` | [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) | yes | The SKU/type-level passport this physical unit is an instance of, masked by the caller's tier. | | `restrictedData` | [BatteryUnitRestrictedDataNotice](/schemas/BatteryUnitRestrictedDataNotice.md) | no | Present ONLY in anonymous (public-tier) responses. | | `currentState` | — | no | Present ONLY in owner/grant-tier responses: the most recent recorded measurement, or null when the unit has no events. | | `dynamicData` | array<[BatteryUnitEventNode](/schemas/BatteryUnitEventNode.md)> | no | Present ONLY in owner/grant-tier responses: append-only telemetry history, newest first, capped at the 500 most recent events. | | `createdAt` | string | yes | — | | `updatedAt` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "Public JSON-LD document for one individual serialised battery unit (EU Battery Regulation). The listed required keys are always present. EXACTLY ONE of two tier-dependent groups is added: anonymous (public) responses carry `restrictedData` (Annex XIII(2)-(4) notice) and OMIT `currentState`/`dynamicData` entirely; owner/grant (privileged) responses carry `currentState` (latest measurement or `null`) and `dynamicData` (up to 500 events, newest first) and omit `restrictedData`. The embedded `ofModel` passport is masked by the caller's tier like `GET /passport/{id}`.", "required": [ "@context", "@type", "@id", "id", "serialNumber", "digitalLinkUri", "status", "manufacturedAt", "repurposedFrom", "successorUnits", "ofModel", "createdAt", "updatedAt" ], "properties": { "@context": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": "The context URL `https://opendpp-node.eu/contexts/dpp/v1` plus a fixed inline term map for the battery-unit terms." }, "@type": { "type": "string", "const": "BatteryUnit" }, "@id": { "type": "string", "format": "uri", "description": "The unit's GS1 Digital Link URI (AI-21 = the real physical serial)." }, "id": { "type": "string" }, "serialNumber": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,20}$", "description": "The physical battery serial (the real GS1 AI-21 value; unique within its SKU/type passport)." }, "digitalLinkUri": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "IN_SERVICE", "DECOMMISSIONED", "RECALLED", "REPURPOSED", "REMANUFACTURED", "REUSED", "WASTE", "RECYCLED" ], "description": "Annex XIII battery-status vocabulary. A `RECYCLED` (or ceased) unit is never served as a 200 — its URL answers 410 with the tombstone document instead." }, "manufacturedAt": { "type": [ "string", "null" ], "format": "date-time" }, "repurposedFrom": { "anyOf": [ { "$ref": "#/components/schemas/BatteryUnitLineageRef" }, { "type": "null" } ], "description": "Lineage: the original unit this repurposed/remanufactured battery came from. The link itself is public." }, "successorUnits": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitLineageRef" }, "description": "Units re-placed on the market under a new passport derived from this one (empty array when none)." }, "ofModel": { "$ref": "#/components/schemas/PublicPassportJsonLd", "description": "The SKU/type-level passport this physical unit is an instance of, masked by the caller's tier." }, "restrictedData": { "$ref": "#/components/schemas/BatteryUnitRestrictedDataNotice", "description": "Present ONLY in anonymous (public-tier) responses." }, "currentState": { "anyOf": [ { "$ref": "#/components/schemas/BatteryUnitCurrentState" }, { "type": "null" } ], "description": "Present ONLY in owner/grant-tier responses: the most recent recorded measurement, or `null` when the unit has no events." }, "dynamicData": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/BatteryUnitEventNode" }, "description": "Present ONLY in owner/grant-tier responses: append-only telemetry history, newest first, capped at the 500 most recent events." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } ``` ## Used by - [resolvePublicBatteryUnit](/operations/resolvePublicBatteryUnit.md) (`GET /unit/{id}`) ================================================================================ # FILE: /okf/schemas/PublicFacilityNode.md ================================================================================ --- type: Schema title: PublicFacilityNode description: Embedded manufacturing-facility JSON-LD node — the GS1 GLN-backed Unique Facility Identifier (UFI, EN 18219). resource: https://opendpp-node.eu/openapi.json#/components/schemas/PublicFacilityNode tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Embedded manufacturing-facility JSON-LD node — the GS1 GLN-backed Unique Facility Identifier (UFI, EN 18219). The five listed fields are public; `streetAddress`/`city`/`postalCode` appear ONLY in owner-tier responses (never via legitimate-interest grants). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@type` | string | yes | — | | `id` | string | yes | — | | `gln` | string | yes | GS1 GLN-13 with a valid modulo-10 check digit. | | `name` | string | yes | — | | `activity` | string,null | yes | What the facility does in the chain, e.g. cell assembly. | | `country` | string | yes | ISO 3166-1 alpha-2 country code. | | `streetAddress` | string,null | no | Owner tier only — omitted from public and grant-tier responses. | | `city` | string,null | no | Owner tier only. | | `postalCode` | string,null | no | Owner tier only. | ## JSON Schema ```json { "type": "object", "description": "Embedded manufacturing-facility JSON-LD node — the GS1 GLN-backed Unique Facility Identifier (UFI, EN 18219). The five listed fields are public; `streetAddress`/`city`/`postalCode` appear ONLY in owner-tier responses (never via legitimate-interest grants).", "required": [ "@type", "id", "gln", "name", "activity", "country" ], "properties": { "@type": { "type": "string", "const": "Facility" }, "id": { "type": "string" }, "gln": { "type": "string", "pattern": "^[0-9]{13}$", "description": "GS1 GLN-13 with a valid modulo-10 check digit." }, "name": { "type": "string" }, "activity": { "type": [ "string", "null" ], "description": "What the facility does in the chain, e.g. `cell assembly`." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "streetAddress": { "type": [ "string", "null" ], "description": "Owner tier only — omitted from public and grant-tier responses." }, "city": { "type": [ "string", "null" ], "description": "Owner tier only." }, "postalCode": { "type": [ "string", "null" ], "description": "Owner tier only." } } } ``` ## Used by - schema [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) ================================================================================ # FILE: /okf/schemas/PublicPassportJsonLd.md ================================================================================ --- type: Schema title: PublicPassportJsonLd description: The public, redacted JSON-LD Digital Product Passport document (application/ld+json). resource: https://opendpp-node.eu/openapi.json#/components/schemas/PublicPassportJsonLd tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The public, redacted JSON-LD Digital Product Passport document (`application/ld+json`). All listed top-level keys are ALWAYS present (`null` where not applicable). Additionally, every key of the (masked) `metadata` object — except the reserved document keys (`@context`, `@type`, `@id`, `id`, `productId`, `digitalLinkUri`, `digitalSeal`, `signingPublicKey`, `status`, `archivedAt`, `retentionUntil`, `proof`, `createdAt`, `updatedAt`, `economicOperator`, `manufacturingFacility`, `metadata`) — is ALSO flattened onto the document root for direct semantic-graph querying (hence `additionalProperties: true`); flattened values are identical to the corresponding `metadata` values, including redaction placeholders. Tier-masked metadata keys are replaced (in both places) with the literal string `[REDACTED - Privileged Access Required]`. Masking by tier: anonymous public callers lose the per-category restricted keys (category `batteries`: `detailedPerformance`, `lifecycleAndInUse`, `circularityAndDisassembly` — masked only when actually present) AND the owner-only key `facilityDetails`; legitimate-interest/authority grant holders lose only `facilityDetails`; owner-tier responses are unmasked and additionally include the facility street address fields. Note: `facilityDetails` is placeholder-masked in EVERY non-owner response, even when the underlying metadata never contained the key — in that case it has no entry in `proof.redactedLeaves`. Each masked key that exists in the sealed metadata keeps its true Merkle leaf hash in `proof.redactedLeaves`, so the seal stays verifiable offline after redaction (see `MerkleTreeAttestationProof` for the reconstruction rule). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | array<—> | yes | Exactly two entries: the context URL https://opendpp-node.eu/contexts/dpp/v1 and an inline term map covering the 9 fixed DPP terms (DigitalProductPassport, eco… | | `@type` | string | yes | — | | `@id` | string | yes | The passport's canonical GS1 Digital Link URI (same value as digitalLinkUri). | | `id` | string | yes | Server-assigned passport UUID. | | `productId` | string | yes | Caller-supplied product identifier: a GTIN-14 (^[0-9]{14}$ with valid GS1 modulo-10 check digit), a GRAI (^[0-9]{14}[A-Za-z0-9]{0,16}$), or a free-form SKU. | | `digitalLinkUri` | string | yes | SKU/type-level GS1 Digital Link URI: {origin}/{01|8003}/{productId} (AI-21 carries the passport UUID at SKU level; individual units carry their physical serial… | | `digitalSeal` | string,null | yes | ADVANCED electronic seal: base64 ECDSA prime256v1 (P-256) signature over the Merkle root of the key-sorted metadata. | | `signingPublicKey` | string,null | yes | PEM public key that verifies digitalSeal. | | `status` | string | yes | Passport lifecycle status (serialized as ACTIVE when unset). | | `archivedAt` | string,null | yes | Soft-delete marker (owner off-boarded / decommissioned). | | `retentionUntil` | string,null | yes | Minimum-availability deadline; the passport is never purged before this instant. | | `proof` | — | yes | Present (non-null) only when the passport is sealed (digitalSeal set). | | `createdAt` | string | yes | — | | `updatedAt` | string | yes | — | | `economicOperator` | — | yes | The economic operator (manufacturer/importer/retailer) responsible for the product. | | `manufacturingFacility` | — | yes | GLN-backed Unique Facility Identifier node (EN 18219), or null when no facility is linked. | | `metadata` | object | yes | The ESPR category metadata, tier-masked: keys above the caller's tier hold the literal string [REDACTED - Privileged Access Required] instead of their value. | ## JSON Schema ```json { "type": "object", "description": "The public, redacted JSON-LD Digital Product Passport document (`application/ld+json`). All listed top-level keys are ALWAYS present (`null` where not applicable). Additionally, every key of the (masked) `metadata` object — except the reserved document keys (`@context`, `@type`, `@id`, `id`, `productId`, `digitalLinkUri`, `digitalSeal`, `signingPublicKey`, `status`, `archivedAt`, `retentionUntil`, `proof`, `createdAt`, `updatedAt`, `economicOperator`, `manufacturingFacility`, `metadata`) — is ALSO flattened onto the document root for direct semantic-graph querying (hence `additionalProperties: true`); flattened values are identical to the corresponding `metadata` values, including redaction placeholders. Tier-masked metadata keys are replaced (in both places) with the literal string `[REDACTED - Privileged Access Required]`. Masking by tier: anonymous public callers lose the per-category restricted keys (category `batteries`: `detailedPerformance`, `lifecycleAndInUse`, `circularityAndDisassembly` — masked only when actually present) AND the owner-only key `facilityDetails`; legitimate-interest/authority grant holders lose only `facilityDetails`; owner-tier responses are unmasked and additionally include the facility street address fields. Note: `facilityDetails` is placeholder-masked in EVERY non-owner response, even when the underlying metadata never contained the key — in that case it has no entry in `proof.redactedLeaves`. Each masked key that exists in the sealed metadata keeps its true Merkle leaf hash in `proof.redactedLeaves`, so the seal stays verifiable offline after redaction (see `MerkleTreeAttestationProof` for the reconstruction rule).", "additionalProperties": true, "required": [ "@context", "@type", "@id", "id", "productId", "digitalLinkUri", "digitalSeal", "signingPublicKey", "status", "archivedAt", "retentionUntil", "proof", "createdAt", "updatedAt", "economicOperator", "manufacturingFacility", "metadata" ], "properties": { "@context": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": "Exactly two entries: the context URL `https://opendpp-node.eu/contexts/dpp/v1` and an inline term map covering the 9 fixed DPP terms (`DigitalProductPassport`, `economicOperator`, `manufacturingFacility`, `metadata`, `digitalSeal`, `signingPublicKey`, `status`, `archivedAt`, `retentionUntil`) plus one generated term per metadata key (`https://opendpp-node.eu/contexts/dpp/v1#`)." }, "@type": { "type": "string", "const": "DigitalProductPassport" }, "@id": { "type": "string", "format": "uri", "description": "The passport's canonical GS1 Digital Link URI (same value as `digitalLinkUri`)." }, "id": { "type": "string", "description": "Server-assigned passport UUID." }, "productId": { "type": "string", "description": "Caller-supplied product identifier: a GTIN-14 (`^[0-9]{14}$` with valid GS1 modulo-10 check digit), a GRAI (`^[0-9]{14}[A-Za-z0-9]{0,16}$`), or a free-form SKU." }, "digitalLinkUri": { "type": "string", "format": "uri", "description": "SKU/type-level GS1 Digital Link URI: `{origin}/{01|8003}/{productId}` (AI-21 carries the passport UUID at SKU level; individual units carry their physical serial instead)." }, "digitalSeal": { "type": [ "string", "null" ], "description": "ADVANCED electronic seal: base64 ECDSA prime256v1 (P-256) signature over the Merkle root of the key-sorted metadata. `null` when the passport has not been sealed." }, "signingPublicKey": { "type": [ "string", "null" ], "description": "PEM public key that verifies `digitalSeal`. `null` when unsealed." }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "RECALLED", "DECOMMISSIONED" ], "description": "Passport lifecycle status (serialized as `ACTIVE` when unset). `DRAFT` is only ever visible to owner-tier callers — public/grant resolution of a draft returns 404." }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete marker (owner off-boarded / decommissioned). Archived passports remain publicly resolvable (ESPR persistence duty)." }, "retentionUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "Minimum-availability deadline; the passport is never purged before this instant." }, "proof": { "anyOf": [ { "$ref": "#/components/schemas/MerkleTreeAttestationProof" }, { "type": "null" } ], "description": "Present (non-null) only when the passport is sealed (`digitalSeal` set)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "economicOperator": { "anyOf": [ { "$ref": "#/components/schemas/EconomicOperatorNode" }, { "type": "null" } ], "description": "The economic operator (manufacturer/importer/retailer) responsible for the product. Public in all tiers." }, "manufacturingFacility": { "anyOf": [ { "$ref": "#/components/schemas/PublicFacilityNode" }, { "type": "null" } ], "description": "GLN-backed Unique Facility Identifier node (EN 18219), or `null` when no facility is linked. GLN, name, activity and country are public; street-address fields appear only in owner-tier responses." }, "metadata": { "type": "object", "additionalProperties": true, "description": "The ESPR category metadata, tier-masked: keys above the caller's tier hold the literal string `[REDACTED - Privileged Access Required]` instead of their value." } } } ``` ## Used by - [getPassport](/operations/getPassport.md) (`GET /api/v1/passports/{id}`) - [resolvePublicPassport](/operations/resolvePublicPassport.md) (`GET /passport/{id}`) - [resolveGs1Gtin](/operations/resolveGs1Gtin.md) (`GET /01/{gtin14}`) - [resolveGs1Grai](/operations/resolveGs1Grai.md) (`GET /8003/{grai}`) - schema [BatteryUnitJsonLd](/schemas/BatteryUnitJsonLd.md) - schema [PassportIngestCreated](/schemas/PassportIngestCreated.md) - schema [PassportUpdateResponse](/schemas/PassportUpdateResponse.md) - schema [PassportSealResponse](/schemas/PassportSealResponse.md) - schema [PassportStatusUpdateResponse](/schemas/PassportStatusUpdateResponse.md) - schema [PublicBatteryUnitJsonLd](/schemas/PublicBatteryUnitJsonLd.md) - schema [WebhookEnvelope](/schemas/WebhookEnvelope.md) ================================================================================ # FILE: /okf/schemas/RecordBatteryUnitEventRequest.md ================================================================================ --- type: Schema title: RecordBatteryUnitEventRequest description: One telemetry record. resource: https://opendpp-node.eu/openapi.json#/components/schemas/RecordBatteryUnitEventRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One telemetry record. All measurements are optional and independently nullable; numeric ranges are enforced with 400 on violation. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `eventType` | [BatteryUnitEventType](/schemas/BatteryUnitEventType.md) | yes | — | | `stateOfHealth` | number,null | no | State of health, percent (0–100). | | `cycleCount` | number,null | no | Cumulative full-equivalent cycles. | | `remainingCapacityAh` | number,null | no | Remaining capacity, ampere-hours. | | `temperatureC` | number,null | no | Observed temperature, °C. | | `payload` | object,array,null | no | Free-form JSON with additional telemetry/context. | | `recordedAt` | string,number | no | When the measurement was taken. | | `status` | [BatteryUnitStatus](/schemas/BatteryUnitStatus.md) | no | Optional status transition, applied to the unit in the same transaction when it differs from the current status (works with any eventType; conventionally paire… | ## JSON Schema ```json { "type": "object", "description": "One telemetry record. All measurements are optional and independently nullable; numeric ranges are enforced with 400 on violation.", "properties": { "eventType": { "$ref": "#/components/schemas/BatteryUnitEventType" }, "stateOfHealth": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "State of health, percent (0–100)." }, "cycleCount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Cumulative full-equivalent cycles. Fractional values are accepted but truncated to an integer before persisting." }, "remainingCapacityAh": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Remaining capacity, ampere-hours." }, "temperatureC": { "type": [ "number", "null" ], "minimum": -273.15, "maximum": 10000, "description": "Observed temperature, °C." }, "payload": { "type": [ "object", "array", "null" ], "description": "Free-form JSON with additional telemetry/context. Objects **and arrays** pass the server's `typeof` check and are persisted verbatim; any other value (string, number, boolean) — and an explicit `null` — is silently dropped and stored as `null`." }, "recordedAt": { "type": [ "string", "number" ], "description": "When the measurement was taken. Any value accepted by JavaScript `Date` parsing (ISO 8601 recommended; epoch milliseconds also work); 400 if unparseable. Defaults to the server's current time." }, "status": { "$ref": "#/components/schemas/BatteryUnitStatus", "description": "Optional status transition, applied to the unit in the same transaction when it differs from the current status (works with any `eventType`; conventionally paired with `STATUS_CHANGE`). Transitioning to `RECYCLED` stamps `ceasedAt` (if not already set; never cleared) and turns the public unit view into a 410 tombstone; `RECYCLED` is terminal — once the unit's status is `RECYCLED` every further event is refused (400 `Terminal Unit Status`), so the status can never change again." } }, "required": [ "eventType" ] } ``` ## Used by - [recordBatteryUnitEvent](/operations/recordBatteryUnitEvent.md) (`POST /api/v1/units/{id}/events`) ================================================================================ # FILE: /okf/schemas/RecordBatteryUnitEventResponse.md ================================================================================ --- type: Schema title: RecordBatteryUnitEventResponse description: Confirmation that a dynamic-data record was appended to a battery unit, echoing the stored event. resource: https://opendpp-node.eu/openapi.json#/components/schemas/RecordBatteryUnitEventResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Confirmation that a dynamic-data record was appended to a battery unit, echoing the stored event. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | — | | `event` | [BatteryUnitEventRow](/schemas/BatteryUnitEventRow.md) | yes | — | ## JSON Schema ```json { "description": "Confirmation that a dynamic-data record was appended to a battery unit, echoing the stored event.", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Dynamic data recorded" }, "event": { "$ref": "#/components/schemas/BatteryUnitEventRow" } }, "required": [ "success", "message", "event" ] } ``` ## Used by - [recordBatteryUnitEvent](/operations/recordBatteryUnitEvent.md) (`POST /api/v1/units/{id}/events`) ================================================================================ # FILE: /okf/schemas/RegisterOperatorRequest.md ================================================================================ --- type: Schema title: RegisterOperatorRequest description: "An economic operator to register: its legal name and registration identifier, with an optional identifier scheme and supply-chain role." resource: https://opendpp-node.eu/openapi.json#/components/schemas/RegisterOperatorRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- An economic operator to register: its legal name and registration identifier, with an optional identifier scheme and supply-chain role. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `name` | string | yes | Legal/display name. | | `regId` | string | yes | Official registration id (EORI, VAT, DUNS, or national registry id). | | `regIdScheme` | string,null | no | Optional declaration of what kind of id regId is. | | `role` | string | no | Supply-chain role, free text — e.g. MANUFACTURER, IMPORTER, RETAILER. | ## JSON Schema ```json { "description": "An economic operator to register: its legal name and registration identifier, with an optional identifier scheme and supply-chain role.", "type": "object", "required": [ "name", "regId" ], "properties": { "name": { "type": "string", "description": "Legal/display name. Ignored if your workspace already has an operator with this `regId` (the existing record is returned instead)." }, "regId": { "type": "string", "description": "Official registration id (EORI, VAT, DUNS, or national registry id). Unique within your workspace; immutable after registration. Fabricated `EORI-MOCK…` ids are rejected. When `regIdScheme` is `EORI`, must match `^[A-Z]{2}[A-Za-z0-9]{1,15}$` (e.g. `DE1234567890`)." }, "regIdScheme": { "type": [ "string", "null" ], "description": "Optional declaration of what kind of id `regId` is. Allowed values: `EORI`, `VAT`, `DUNS`, `NATIONAL`, `OTHER` — matched case-insensitively (uppercased server-side). Any other value is rejected with `400`. Omit or send `null` for an unspecified national/business id. Ignored when binding to an existing operator." }, "role": { "type": "string", "default": "MANUFACTURER", "description": "Supply-chain role, free text — e.g. `MANUFACTURER`, `IMPORTER`, `RETAILER`. Defaults to `MANUFACTURER`. Ignored when binding to an existing operator." } } } ``` ## Used by - [registerOperator](/operations/registerOperator.md) (`POST /api/v1/operators`) ================================================================================ # FILE: /okf/schemas/RegisterOperatorResponse.md ================================================================================ --- type: Schema title: RegisterOperatorResponse description: Confirmation that an economic operator was registered, carrying the stored record and any non-blocking advisories. resource: https://opendpp-node.eu/openapi.json#/components/schemas/RegisterOperatorResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Confirmation that an economic operator was registered, carrying the stored record and any non-blocking advisories. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | Always "Economic Operator supplier registered successfully" (also when an existing operator was bound rather than created). | | `operator` | [OperatorRow](/schemas/OperatorRow.md) | yes | — | | `warnings` | array<[AdvisoryItem](/schemas/AdvisoryItem.md)> | yes | Non-blocking advisories. | ## JSON Schema ```json { "description": "Confirmation that an economic operator was registered, carrying the stored record and any non-blocking advisories.", "type": "object", "required": [ "success", "message", "operator", "warnings" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "Always `\"Economic Operator supplier registered successfully\"` (also when an existing operator was bound rather than created)." }, "operator": { "$ref": "#/components/schemas/OperatorRow" }, "warnings": { "type": "array", "description": "Non-blocking advisories. Carries a single EORI-not-found note when the OPT-IN EORI existence check is enabled and a declared EORI is not found in the EU EOS register. Empty `[]` otherwise. Never blocks registration.", "items": { "$ref": "#/components/schemas/AdvisoryItem" } } } } ``` ## Used by - [registerOperator](/operations/registerOperator.md) (`POST /api/v1/operators`) ================================================================================ # FILE: /okf/schemas/RestoreOperatorResponse.md ================================================================================ --- type: Schema title: RestoreOperatorResponse description: Outcome of restoring an archived economic operator, including how many of its passports were restored. resource: https://opendpp-node.eu/openapi.json#/components/schemas/RestoreOperatorResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Outcome of restoring an archived economic operator, including how many of its passports were restored. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `restoredPassports` | integer | yes | Number of archived passports returned to the active catalogue (archivedAt and retentionUntil cleared). | ## JSON Schema ```json { "description": "Outcome of restoring an archived economic operator, including how many of its passports were restored.", "type": "object", "required": [ "success", "restoredPassports" ], "properties": { "success": { "type": "boolean", "const": true }, "restoredPassports": { "type": "integer", "minimum": 0, "description": "Number of archived passports returned to the active catalogue (`archivedAt` and `retentionUntil` cleared). Passports independently DECOMMISSIONED are not restored and not counted." } } } ``` ## Used by - [restoreOperator](/operations/restoreOperator.md) (`POST /api/v1/operators/{id}/restore`) ================================================================================ # FILE: /okf/schemas/RotateTenantKeysResponse.md ================================================================================ --- type: Schema title: RotateTenantKeysResponse description: Confirmation that the workspace's signing key was rotated, returning the new public key. resource: https://opendpp-node.eu/openapi.json#/components/schemas/RotateTenantKeysResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Confirmation that the workspace's signing key was rotated, returning the new public key. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | Outcome message. | | `publicKey` | string | yes | The new ECDSA prime256v1 (P-256) public key, PEM-encoded (SPKI, -----BEGIN PUBLIC KEY----- block, trailing newline). | ## JSON Schema ```json { "description": "Confirmation that the workspace's signing key was rotated, returning the new public key.", "type": "object", "required": [ "success", "message", "publicKey" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "Outcome message. On a first provisioning: `\"eIDAS Asymmetric Key Pair generated in secure DB custody successfully.\"` On a rotation, a message noting that the previous key is retired but retained in your DID document so existing credentials keep verifying." }, "publicKey": { "type": "string", "description": "The new ECDSA prime256v1 (P-256) public key, PEM-encoded (SPKI, `-----BEGIN PUBLIC KEY-----` block, trailing newline). The matching private key is held only AES-256-GCM-encrypted in the platform vault and is never returned." } } } ``` ## Used by - [rotateTenantKeys](/operations/rotateTenantKeys.md) (`POST /api/v1/tenants/rotate-keys`) ================================================================================ # FILE: /okf/schemas/SealCertificateReport.md ================================================================================ --- type: Schema title: SealCertificateReport description: "Present only for x5c-carrying proofs on a verified: true outcome whose chain is TRUSTED — chainValid AND keyMatchesProof both true (the two policy verified: false responses AND any untrusted-chain outcome omit it): the certified legal iden…" resource: https://opendpp-node.eu/openapi.json#/components/schemas/SealCertificateReport tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Present only for x5c-carrying proofs on a `verified: true` outcome whose chain is TRUSTED — `chainValid` AND `keyMatchesProof` both true (the two policy `verified: false` responses AND any untrusted-chain outcome omit it): the certified legal identity of the seal creator. An untrusted chain is never surfaced, so an emitted report always has `chainValid: true`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `subject` | string | no | Leaf-certificate subject (multi-line RDN string as produced by Node's X509Certificate, e.g. CN=OpenDPP Demo Eco Industries Seal). | | `issuer` | string | no | Leaf-certificate issuer RDN string. | | `validFrom` | string | no | X.509 textual date, e.g. Jan 10 00:00:00 2026 GMT — NOT ISO 8601. | | `validTo` | string | no | X.509 textual date — NOT ISO 8601. | | `chainValid` | boolean | yes | True only when every chain link signature-verifies, every certificate is within its validity window, AND the top of the chain is anchored to this node's seal C… | | `keyMatchesProof` | boolean | no | True when the leaf SPKI equals the supplied publicKey (whitespace-insensitive), or when no explicit public key was supplied (the leaf key was used). | | `error` | string | no | Present only when the chain could not be parsed. | ## JSON Schema ```json { "type": "object", "description": "Present only for x5c-carrying proofs on a `verified: true` outcome whose chain is TRUSTED — `chainValid` AND `keyMatchesProof` both true (the two policy `verified: false` responses AND any untrusted-chain outcome omit it): the certified legal identity of the seal creator. An untrusted chain is never surfaced, so an emitted report always has `chainValid: true`.", "required": [ "chainValid" ], "properties": { "subject": { "type": "string", "description": "Leaf-certificate subject (multi-line RDN string as produced by Node's X509Certificate, e.g. `CN=OpenDPP Demo Eco Industries Seal`)." }, "issuer": { "type": "string", "description": "Leaf-certificate issuer RDN string." }, "validFrom": { "type": "string", "description": "X.509 textual date, e.g. `Jan 10 00:00:00 2026 GMT` — NOT ISO 8601." }, "validTo": { "type": "string", "description": "X.509 textual date — NOT ISO 8601." }, "chainValid": { "type": "boolean", "description": "True only when every chain link signature-verifies, every certificate is within its validity window, AND the top of the chain is anchored to this node's seal CA (fingerprint match or signature under the CA key)." }, "keyMatchesProof": { "type": "boolean", "description": "True when the leaf SPKI equals the supplied `publicKey` (whitespace-insensitive), or when no explicit public key was supplied (the leaf key was used)." }, "error": { "type": "string", "const": "Unparseable x5c certificate chain", "description": "Present only when the chain could not be parsed." } } } ``` ## Used by - schema [SealVerifyResponse](/schemas/SealVerifyResponse.md) ================================================================================ # FILE: /okf/schemas/SealTimestampReport.md ================================================================================ --- type: Schema title: SealTimestampReport description: "Present only when payload.proof.rfc3161.token was supplied AND verification proceeds past the key-registration and operator-binding gates (the two policy verified: false responses omit it)." resource: https://opendpp-node.eu/openapi.json#/components/schemas/SealTimestampReport tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Present only when `payload.proof.rfc3161.token` was supplied AND verification proceeds past the key-registration and operator-binding gates (the two policy `verified: false` responses omit it). Reports presence, the TSA-asserted genTime from the token's TSTInfo, and — when the node has a TSA trust anchor configured — `timeAuthenticated`: the result of verifying the token's CMS SignedData signature over its TSTInfo and chaining the signer certificate to that anchor. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `present` | boolean | yes | — | | `genTime` | string,null | yes | TSA-asserted generation time (ISO 8601), or null when the token's TSTInfo could not be parsed. | | `timeAuthenticated` | boolean | no | True only when the token's RFC 3161 CMS SignedData signature verifies over its TSTInfo AND the signer passes full trust-path validation to the node's configure… | | `note` | string | no | Present only when genTime is null. | ## JSON Schema ```json { "type": "object", "description": "Present only when `payload.proof.rfc3161.token` was supplied AND verification proceeds past the key-registration and operator-binding gates (the two policy `verified: false` responses omit it). Reports presence, the TSA-asserted genTime from the token's TSTInfo, and — when the node has a TSA trust anchor configured — `timeAuthenticated`: the result of verifying the token's CMS SignedData signature over its TSTInfo and chaining the signer certificate to that anchor.", "required": [ "present", "genTime" ], "properties": { "present": { "type": "boolean", "const": true }, "genTime": { "type": [ "string", "null" ], "format": "date-time", "description": "TSA-asserted generation time (ISO 8601), or null when the token's TSTInfo could not be parsed." }, "timeAuthenticated": { "type": "boolean", "description": "True only when the token's RFC 3161 CMS SignedData signature verifies over its TSTInfo AND the signer passes full trust-path validation to the node's configured TSA trust anchor: the signer is an end-entity timestamping certificate (a CRITICAL `id-kp-timeStamping` EKU, not a CA) that is VALID at the asserted `genTime` and chains through CA-constrained, genTime-valid intermediates to the anchor (itself a CA valid at `genTime`). False when the signature fails, when the path is not policy-valid, and when no TSA CA is configured (the asserted `genTime` is then unauthenticated). This is the node's own cryptographic check and does not replace a verifier's independent `openssl ts -verify`." }, "note": { "type": "string", "const": "token present but TSTInfo could not be parsed", "description": "Present only when `genTime` is null." } } } ``` ## Used by - schema [SealVerifyResponse](/schemas/SealVerifyResponse.md) ================================================================================ # FILE: /okf/schemas/SealVerifyRequest.md ================================================================================ --- type: Schema title: SealVerifyRequest description: Verification request. resource: https://opendpp-node.eu/openapi.json#/components/schemas/SealVerifyRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Verification request. Only `payload` is strictly required: `signature` and `publicKey` are extracted from `payload.proof` (proofValue/signatureValue, publicKeyPem, or the x5c leaf SPKI) when omitted, and the request fails 400 only if either is still missing after extraction. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `payload` | object | yes | The sealed passport document to verify — typically the JSON-LD passport document exactly as resolved from the public endpoints, or any {passportId, productId,… | | `signature` | string | no | Base64 ECDSA (P-256 / SHA-256) seal signature. | | `publicKey` | string | no | PEM (SPKI) public key of the sealing tenant. | ## JSON Schema ```json { "type": "object", "description": "Verification request. Only `payload` is strictly required: `signature` and `publicKey` are extracted from `payload.proof` (proofValue/signatureValue, publicKeyPem, or the x5c leaf SPKI) when omitted, and the request fails 400 only if either is still missing after extraction.", "required": [ "payload" ], "properties": { "payload": { "type": "object", "description": "The sealed passport document to verify — typically the JSON-LD passport document exactly as resolved from the public endpoints, or any `{passportId, productId, metadata, operator}` payload. Only the fields below are interpreted; all other properties are preserved and participate in the whole-payload signature fallback.", "properties": { "metadata": { "type": "object", "description": "The sealed metadata object — the SHA-256 Merkle tree is rebuilt over its top-level properties (every leaf recomputed from the actual values; caller-supplied redacted-leaf hashes are not accepted). When the `metadata` key is entirely ABSENT, the whole `payload` object is treated as the metadata for the Merkle phase; a present-but-non-object value skips the Merkle phase (only the whole-payload fallback runs)." }, "operator": { "type": "object", "description": "Declared economic operator. A present `regId` triggers the fail-closed operator-binding gate.", "properties": { "name": { "type": "string" }, "regId": { "type": "string", "description": "Operator registration id (e.g. EORI-style `EU-DEFAULT-001`). Must resolve to a registered Economic Operator bound to the signing tenant, or verification fails (`verified: false`)." } } }, "economicOperator": { "type": "object", "description": "Alternative location for the declared operator id — `economicOperator.regId` is checked when `operator.regId` is absent.", "properties": { "regId": { "type": "string" } } }, "proof": { "type": "object", "description": "Embedded W3C-style proof block. Sources for the signature, public key, certificate chain and RFC 3161 token when the top-level fields are omitted.", "properties": { "type": { "type": "string" }, "proofValue": { "type": "string", "description": "Base64 ECDSA seal — used as `signature` when the top-level field is absent." }, "signatureValue": { "type": "string", "description": "Legacy alias for `proofValue` (checked second)." }, "publicKeyPem": { "type": "string", "description": "PEM (SPKI) public key — used as `publicKey` when the top-level field is absent." }, "x5c": { "type": "array", "items": { "type": "string" }, "description": "X.509 certificate chain, base64 DER, LEAF FIRST. Enables the `certificate` report; the leaf's SPKI also serves as the public key when none is otherwise supplied." }, "rfc3161": { "type": "object", "properties": { "token": { "type": "string", "description": "RFC 3161 TimeStampToken (base64 DER CMS ContentInfo) — enables the `timestamp` report." } } } } } }, "additionalProperties": true }, "signature": { "type": "string", "description": "Base64 ECDSA (P-256 / SHA-256) seal signature. Optional when `payload.proof.proofValue` (or `signatureValue`) is present." }, "publicKey": { "type": "string", "description": "PEM (SPKI) public key of the sealing tenant. Optional when `payload.proof.publicKeyPem` or an `x5c` chain is present. CRLF line endings are normalized before matching." } } } ``` ## Used by - [verifyPassportSeal](/operations/verifyPassportSeal.md) (`POST /api/v1/audit/verify`) ================================================================================ # FILE: /okf/schemas/SealVerifyResponse.md ================================================================================ --- type: Schema title: SealVerifyResponse description: Always HTTP 200 once the request is well-formed. resource: https://opendpp-node.eu/openapi.json#/components/schemas/SealVerifyResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Always HTTP 200 once the request is well-formed. `verified: false` covers both cryptographic failure and the two registration/binding policy failures — the policy failures add a `message` and OMIT `certificate`/`timestamp` even when an x5c chain or RFC 3161 token was supplied. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `verified` | boolean | yes | — | | `message` | string | no | Present only on the two policy failures: unregistered public key, or a declared operator not bound to the signing tenant. | | `certificate` | [SealCertificateReport](/schemas/SealCertificateReport.md) | no | — | | `timestamp` | [SealTimestampReport](/schemas/SealTimestampReport.md) | no | — | ## JSON Schema ```json { "type": "object", "description": "Always HTTP 200 once the request is well-formed. `verified: false` covers both cryptographic failure and the two registration/binding policy failures — the policy failures add a `message` and OMIT `certificate`/`timestamp` even when an x5c chain or RFC 3161 token was supplied.", "required": [ "success", "verified" ], "properties": { "success": { "type": "boolean", "const": true }, "verified": { "type": "boolean" }, "message": { "type": "string", "description": "Present only on the two policy failures: unregistered public key, or a declared operator not bound to the signing tenant.", "enum": [ "Cryptographic verification failed: The public key used to seal this passport is not registered to any authorized economic operator tenant on this node.", "Cryptographic verification failed: The economic operator declared in this passport is not a registered operator bound to the signing tenant." ] }, "certificate": { "$ref": "#/components/schemas/SealCertificateReport" }, "timestamp": { "$ref": "#/components/schemas/SealTimestampReport" } } } ``` ## Used by - [verifyPassportSeal](/operations/verifyPassportSeal.md) (`POST /api/v1/audit/verify`) ================================================================================ # FILE: /okf/schemas/SectorJsonSchemaDocument.md ================================================================================ --- type: Schema title: SectorJsonSchemaDocument description: A JSON Schema draft-07 document describing the ESPR metadata payload for one product category, served as application/schema+json. resource: https://opendpp-node.eu/openapi.json#/components/schemas/SectorJsonSchemaDocument tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A JSON Schema **draft-07** document describing the ESPR `metadata` payload for one product category, served as `application/schema+json`. Each known field is annotated server-side with a plain-English `description` from the platform's field-help registry (annotations are AJV-ignored; validation behavior is identical to the raw schema). The same schema (without annotations) validates `metadata` on `POST /api/v1/passports` and the validate-only endpoints. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `$schema` | string | yes | — | | `title` | string | yes | — | | `type` | string | yes | — | | `required` | array | yes | — | | `properties` | object | yes | — | ## JSON Schema ```json { "type": "object", "description": "A JSON Schema **draft-07** document describing the ESPR `metadata` payload for one product category, served as `application/schema+json`. Each known field is annotated server-side with a plain-English `description` from the platform's field-help registry (annotations are AJV-ignored; validation behavior is identical to the raw schema). The same schema (without annotations) validates `metadata` on `POST /api/v1/passports` and the validate-only endpoints.", "additionalProperties": true, "required": [ "$schema", "title", "type", "required", "properties" ], "properties": { "$schema": { "type": "string", "const": "http://json-schema.org/draft-07/schema#" }, "title": { "type": "string" }, "type": { "type": "string", "const": "object" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": true } } } ``` ## Used by - [getSectorSchema](/operations/getSectorSchema.md) (`GET /api/v1/schemas/{category}`) ================================================================================ # FILE: /okf/schemas/SectorVocabularyContext.md ================================================================================ --- type: Schema title: SectorVocabularyContext description: Per-category JSON-LD vocabulary context, returned by GET /api/v1/schemas/{category} when Accept contains application/ld+json. resource: https://opendpp-node.eu/openapi.json#/components/schemas/SectorVocabularyContext tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Per-category JSON-LD vocabulary context, returned by `GET /api/v1/schemas/{category}` when `Accept` contains `application/ld+json`. Fixed shape: `@vocab` is `https://w3id.org/opendpp/schemas/{category}#` plus mappings for `id`, `type`, `category`, `materialComposition`, `originCountry`, `facilityDetails` and `regulatoryCompliance`. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | object | yes | — | ## JSON Schema ```json { "type": "object", "description": "Per-category JSON-LD vocabulary context, returned by `GET /api/v1/schemas/{category}` when `Accept` contains `application/ld+json`. Fixed shape: `@vocab` is `https://w3id.org/opendpp/schemas/{category}#` plus mappings for `id`, `type`, `category`, `materialComposition`, `originCountry`, `facilityDetails` and `regulatoryCompliance`.", "required": [ "@context" ], "properties": { "@context": { "type": "object", "additionalProperties": { "type": "string" } } } } ``` ## Used by - [getSectorSchema](/operations/getSectorSchema.md) (`GET /api/v1/schemas/{category}`) ================================================================================ # FILE: /okf/schemas/SerializeBatteryUnitsRequest.md ================================================================================ --- type: Schema title: SerializeBatteryUnitsRequest description: "Either a single unit object, or a batch wrapper {units: [...]}." resource: https://opendpp-node.eu/openapi.json#/components/schemas/SerializeBatteryUnitsRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Either a single unit object, or a batch wrapper `{units: [...]}`. Precedence: when `units` is present **and is an array** it is used; otherwise the whole body is treated as one unit. (`anyOf`, not `oneOf`: a body carrying both a top-level `serialNumber` and a `units` array matches both shapes and is accepted by the server — `units` wins.) ## JSON Schema ```json { "description": "Either a single unit object, or a batch wrapper `{units: [...]}`. Precedence: when `units` is present **and is an array** it is used; otherwise the whole body is treated as one unit. (`anyOf`, not `oneOf`: a body carrying both a top-level `serialNumber` and a `units` array matches both shapes and is accepted by the server — `units` wins.)", "anyOf": [ { "$ref": "#/components/schemas/BatteryUnitCreateItem" }, { "type": "object", "properties": { "units": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitCreateItem" }, "minItems": 1, "maxItems": 200, "description": "1–200 units per request. An empty array is rejected with 400 `Bad Request`; more than 200 likewise." } }, "required": [ "units" ] } ] } ``` ## Used by - [validateBatteryUnits](/operations/validateBatteryUnits.md) (`POST /api/v1/passports/{passportId}/units/validate`) - [serializeBatteryUnits](/operations/serializeBatteryUnits.md) (`POST /api/v1/passports/{passportId}/units`) ================================================================================ # FILE: /okf/schemas/SerializeBatteryUnitsResponse.md ================================================================================ --- type: Schema title: SerializeBatteryUnitsResponse description: Returned (201) when at least one unit was created. resource: https://opendpp-node.eu/openapi.json#/components/schemas/SerializeBatteryUnitsResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Returned (201) when at least one unit was created. Partial success is possible: skipped items are reported in `errors` while `units` holds the created rows. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | E.g. | | `count` | integer | yes | Number of units actually created (equals units.length). | | `units` | array<[BatteryUnitRow](/schemas/BatteryUnitRow.md)> | yes | — | | `errors` | array | no | Present only when some items were skipped — one plain-English string per skipped item, generally prefixed []. | | `warnings` | array<[AdvisoryItem](/schemas/AdvisoryItem.md)> | yes | Non-blocking advisories. | ## JSON Schema ```json { "type": "object", "description": "Returned (201) when at least one unit was created. Partial success is possible: skipped items are reported in `errors` while `units` holds the created rows.", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "E.g. `Serialised 2 individual unit(s)` or `Serialised 1 individual unit(s), skipped 1`." }, "count": { "type": "integer", "minimum": 1, "description": "Number of units actually created (equals `units.length`)." }, "units": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitRow" } }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Present only when some items were skipped — one plain-English string per skipped item, generally prefixed `[]`." }, "warnings": { "type": "array", "description": "Non-blocking advisories. Carries a single note when the passport's `productId` is NOT a GS1 GTIN — the created units then have no scannable GS1 unit Digital Link (`/01/{gtin}/21/{serial}`) and resolve only via `/unit/{id}`. Empty `[]` for a GTIN-keyed passport.", "items": { "$ref": "#/components/schemas/AdvisoryItem" } } }, "required": [ "success", "message", "count", "units", "warnings" ] } ``` ## Used by - [serializeBatteryUnits](/operations/serializeBatteryUnits.md) (`POST /api/v1/passports/{passportId}/units`) ================================================================================ # FILE: /okf/schemas/ServiceVersion.md ================================================================================ --- type: Schema title: ServiceVersion description: Running API contract version and source build identity, returned by GET /api/v1/version. resource: https://opendpp-node.eu/openapi.json#/components/schemas/ServiceVersion tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Running API contract version and source build identity, returned by `GET /api/v1/version`. The `apiVersion` MAJOR is the safe thing to pin an integration or generated SDK to. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `apiVersion` | string | yes | SemVer of the public API contract currently served (equals the OpenAPI document's info.version; its MAJOR equals the /api/v1 URL major). | | `commit` | string | yes | Short git commit SHA of the running build, or "unknown" when a build did not inject it. | | `builtAt` | string | yes | Build/deploy timestamp (ISO 8601 UTC), or "unknown" when a build did not inject it. | ## JSON Schema ```json { "type": "object", "description": "Running API contract version and source build identity, returned by `GET /api/v1/version`. The `apiVersion` MAJOR is the safe thing to pin an integration or generated SDK to.", "required": [ "apiVersion", "commit", "builtAt" ], "properties": { "apiVersion": { "type": "string", "description": "SemVer of the public API contract currently served (equals the OpenAPI document's `info.version`; its MAJOR equals the `/api/v1` URL major).", "examples": [ "1.0.0" ] }, "commit": { "type": "string", "description": "Short git commit SHA of the running build, or `\"unknown\"` when a build did not inject it.", "examples": [ "a7a96d0", "unknown" ] }, "builtAt": { "type": "string", "description": "Build/deploy timestamp (ISO 8601 UTC), or `\"unknown\"` when a build did not inject it.", "examples": [ "2026-06-12T09:30:00Z", "unknown" ] } } } ``` ## Used by - [getApiVersion](/operations/getApiVersion.md) (`GET /api/v1/version`) ================================================================================ # FILE: /okf/schemas/TraceEventRegistered.md ================================================================================ --- type: Schema title: TraceEventRegistered description: 201 envelope of POST /api/v1/events. resource: https://opendpp-node.eu/openapi.json#/components/schemas/TraceEventRegistered tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- 201 envelope of POST /api/v1/events. Note: `status: "success"` (string), not the usual `success: true` boolean. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `status` | string | yes | — | | `eventId` | string | yes | Server-generated event id. | | `untpVerified` | boolean | yes | — | ## JSON Schema ```json { "type": "object", "description": "201 envelope of POST /api/v1/events. Note: `status: \"success\"` (string), not the usual `success: true` boolean.", "required": [ "status", "eventId", "untpVerified" ], "properties": { "status": { "type": "string", "const": "success" }, "eventId": { "type": "string", "description": "Server-generated event id. Use it with `GET /api/v1/events/{id}/lineage`." }, "untpVerified": { "type": "boolean", "const": true } } } ``` ## Used by - [registerTraceabilityEvent](/operations/registerTraceabilityEvent.md) (`POST /api/v1/events`) ================================================================================ # FILE: /okf/schemas/TraceLineageNode.md ================================================================================ --- type: Schema title: TraceLineageNode description: One node of the recursive upstream lineage DAG. resource: https://opendpp-node.eu/openapi.json#/components/schemas/TraceLineageNode tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One node of the recursive upstream lineage DAG. All keys are always present; `location`, `readPoint` and `issuerDid` are null when unset. `location` mirrors the stored `bizLocation`. A shared ancestor reached through multiple downstream paths appears once under each path (the DAG is expanded into a tree). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `eventId` | string | yes | — | | `eventType` | string | yes | — | | `bizStep` | string | yes | — | | `disposition` | string | yes | — | | `eventTime` | string | yes | — | | `epcs` | array | yes | EPC URIs parsed from the stored EPC list (degrades to [] when unparseable). | | `location` | string,null | yes | The event's stored bizLocation. | | `readPoint` | string,null | yes | — | | `isUntpCompliant` | boolean | yes | — | | `issuerDid` | string,null | yes | — | | `parents` | array<[TraceLineageNode](/schemas/TraceLineageNode.md)> | yes | Upstream parent events (recursive). | ## JSON Schema ```json { "type": "object", "description": "One node of the recursive upstream lineage DAG. All keys are always present; `location`, `readPoint` and `issuerDid` are null when unset. `location` mirrors the stored `bizLocation`. A shared ancestor reached through multiple downstream paths appears once under each path (the DAG is expanded into a tree).", "required": [ "eventId", "eventType", "bizStep", "disposition", "eventTime", "epcs", "location", "readPoint", "isUntpCompliant", "issuerDid", "parents" ], "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "ObjectEvent", "AggregationEvent", "TransformationEvent", "AssociationEvent" ] }, "bizStep": { "type": "string" }, "disposition": { "type": "string" }, "eventTime": { "type": "string", "format": "date-time" }, "epcs": { "type": "array", "items": { "type": "string" }, "description": "EPC URIs parsed from the stored EPC list (degrades to `[]` when unparseable)." }, "location": { "type": [ "string", "null" ], "description": "The event's stored `bizLocation`." }, "readPoint": { "type": [ "string", "null" ] }, "isUntpCompliant": { "type": "boolean" }, "issuerDid": { "type": [ "string", "null" ] }, "parents": { "type": "array", "items": { "$ref": "#/components/schemas/TraceLineageNode" }, "description": "Upstream parent events (recursive). Empty array at the origin of the chain." } } } ``` ## Used by - schema [TraceLineageResponse](/schemas/TraceLineageResponse.md) ================================================================================ # FILE: /okf/schemas/TraceLineageResponse.md ================================================================================ --- type: Schema title: TraceLineageResponse description: The upstream pedigree of a traceability event, as a recursive graph of the events it derives from. resource: https://opendpp-node.eu/openapi.json#/components/schemas/TraceLineageResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The upstream pedigree of a traceability event, as a recursive graph of the events it derives from. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `lineage` | [TraceLineageNode](/schemas/TraceLineageNode.md) | yes | — | ## JSON Schema ```json { "description": "The upstream pedigree of a traceability event, as a recursive graph of the events it derives from.", "type": "object", "required": [ "success", "lineage" ], "properties": { "success": { "type": "boolean", "const": true }, "lineage": { "$ref": "#/components/schemas/TraceLineageNode" } } } ``` ## Used by - [getEventLineage](/operations/getEventLineage.md) (`GET /api/v1/events/{id}/lineage`) ================================================================================ # FILE: /okf/schemas/UntpEventCredential.md ================================================================================ --- type: Schema title: UntpEventCredential description: A UNTP/EPCIS 2.0 traceability event wrapped as a VC-shaped credential. resource: https://opendpp-node.eu/openapi.json#/components/schemas/UntpEventCredential tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A UNTP/EPCIS 2.0 traceability event wrapped as a VC-shaped credential. The only hard structural requirement is `credentialSubject`; the `proof` MUST be a conformant W3C `DataIntegrityProof` (`cryptosuite: "ecdsa-jcs-2019"`) and a missing, non-conformant, or unverifiable proof is rejected with the 400 `Cryptographic Verification Failed` body. Extra properties are permitted — the signature covers `sha256(JCS(proof options)) ‖ sha256(JCS(credential without proof))` (RFC 8785 JCS canonicalization). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `@context` | array | no | — | | `id` | string | no | Credential id (e.g. urn:uuid:...). | | `type` | array | no | — | | `issuer` | string | no | Issuer DID. | | `issuanceDate` | string | no | Fallback for the stored eventTime when credentialSubject.eventTime is absent. | | `credentialSubject` | [UntpEventCredentialSubject](/schemas/UntpEventCredentialSubject.md) | yes | — | | `proof` | [UntpEventProof](/schemas/UntpEventProof.md) | yes | — | ## JSON Schema ```json { "type": "object", "description": "A UNTP/EPCIS 2.0 traceability event wrapped as a VC-shaped credential. The only hard structural requirement is `credentialSubject`; the `proof` MUST be a conformant W3C `DataIntegrityProof` (`cryptosuite: \"ecdsa-jcs-2019\"`) and a missing, non-conformant, or unverifiable proof is rejected with the 400 `Cryptographic Verification Failed` body. Extra properties are permitted — the signature covers `sha256(JCS(proof options)) ‖ sha256(JCS(credential without proof))` (RFC 8785 JCS canonicalization).", "required": [ "credentialSubject", "proof" ], "properties": { "@context": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "description": "Credential id (e.g. `urn:uuid:...`). NOT used as the stored event id — the event primary key is always server-generated." }, "type": { "type": "array", "items": { "type": "string" } }, "issuer": { "type": "string", "description": "Issuer DID. Unless a trusted x5c chain is embedded, the verification key is resolved by EXACT match of the DID's trailing `:`-segment against registered tenant subdomains/company names — e.g. `did:web:opendpp-node.eu:demo` resolves the workspace with subdomain `demo`. For operator-scoped API keys the issuer DID must ALSO contain the bound operator's registration id somewhere in the string (the issuer is checked in preference to `credentialSubject.responsibleOperatorDid`), e.g. `did:web:opendpp-node.eu:EU-DEFAULT-001:demo`. Stored verbatim as the event's `issuerDid`." }, "issuanceDate": { "type": "string", "format": "date-time", "description": "Fallback for the stored `eventTime` when `credentialSubject.eventTime` is absent." }, "credentialSubject": { "$ref": "#/components/schemas/UntpEventCredentialSubject" }, "proof": { "$ref": "#/components/schemas/UntpEventProof" } } } ``` ## Used by - [registerTraceabilityEvent](/operations/registerTraceabilityEvent.md) (`POST /api/v1/events`) ================================================================================ # FILE: /okf/schemas/UntpEventCredentialSubject.md ================================================================================ --- type: Schema title: UntpEventCredentialSubject description: The EPCIS event payload. resource: https://opendpp-node.eu/openapi.json#/components/schemas/UntpEventCredentialSubject tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The EPCIS event payload. `eventType` is effectively required: it is persisted into a server-side enum, and a missing or unknown value is rejected at the persistence layer (surfacing as the 500 `Database Persistence Failed` body, not a 400). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | no | EPC identifier of the subject (e.g. urn:epc:id:sgtin:0950110153.0003.SN-2026-000123). | | `eventType` | string | yes | EPCIS 2.0 event type (server-side enum). | | `action` | string | no | EPCIS action (server-side enum). | | `bizStep` | string | no | CBV business step URI. | | `disposition` | string | no | CBV disposition URI. | | `readPoint` | string | no | Where the event was observed (e.g. geo:41.1496,-8.6109). | | `bizLocation` | string | no | Business location (SGLN URI, DID, or free identifier). | | `eventTime` | string | no | When the event occurred (anything new Date() parses). | | `epcList` | array | no | EPC URIs observed by the event. | | `parentEpc` | string | no | Parent EPC for AggregationEvent. | | `childEpcs` | array | no | Child EPCs for AggregationEvent (stored as JSON verbatim). | | `inputEpcList` | array | no | Input EPCs for TransformationEvent (stored as JSON verbatim). | | `outputEpcList` | array | no | Output EPCs for TransformationEvent (stored as JSON verbatim). | | `originLocation` | object | no | Geographic origin; used only to derive a default readPoint (geo:,) when readPoint is absent. | | `responsibleOperatorDid` | string | no | DID of the responsible economic operator. | ## JSON Schema ```json { "type": "object", "description": "The EPCIS event payload. `eventType` is effectively required: it is persisted into a server-side enum, and a missing or unknown value is rejected at the persistence layer (surfacing as the 500 `Database Persistence Failed` body, not a 400).", "required": [ "eventType" ], "properties": { "id": { "type": "string", "description": "EPC identifier of the subject (e.g. `urn:epc:id:sgtin:0950110153.0003.SN-2026-000123`). When `epcList` is not supplied as an array, the stored EPC list defaults to `[id]` (or `[]` if absent)." }, "eventType": { "type": "string", "enum": [ "ObjectEvent", "AggregationEvent", "TransformationEvent", "AssociationEvent" ], "description": "EPCIS 2.0 event type (server-side enum)." }, "action": { "type": "string", "enum": [ "ADD", "OBSERVE", "DELETE" ], "description": "EPCIS action (server-side enum). Optional — but MUST be absent (or null) on `TransformationEvent`, otherwise 400 `Schema Validation Error`. An unknown value is rejected at the persistence layer (500)." }, "bizStep": { "type": "string", "default": "urn:epcglobal:cbv:bizstep:receiving", "description": "CBV business step URI. Defaults to `urn:epcglobal:cbv:bizstep:receiving`." }, "disposition": { "type": "string", "default": "urn:epcglobal:cbv:disp:in_progress", "description": "CBV disposition URI. Defaults to `urn:epcglobal:cbv:disp:in_progress`." }, "readPoint": { "type": "string", "description": "Where the event was observed (e.g. `geo:41.1496,-8.6109`). When absent and `originLocation` is present, defaults to `geo:,`." }, "bizLocation": { "type": "string", "description": "Business location (SGLN URI, DID, or free identifier). When absent, defaults to `responsibleOperatorDid`." }, "eventTime": { "type": "string", "format": "date-time", "description": "When the event occurred (anything `new Date()` parses). Defaults to the credential `issuanceDate`, else the server clock." }, "epcList": { "type": "array", "items": { "type": "string" }, "description": "EPC URIs observed by the event. A non-array value is replaced with `[credentialSubject.id]` (or `[]`)." }, "parentEpc": { "type": "string", "description": "Parent EPC for AggregationEvent." }, "childEpcs": { "type": "array", "items": { "type": "string" }, "description": "Child EPCs for AggregationEvent (stored as JSON verbatim)." }, "inputEpcList": { "type": "array", "items": { "type": "string" }, "description": "Input EPCs for TransformationEvent (stored as JSON verbatim)." }, "outputEpcList": { "type": "array", "items": { "type": "string" }, "description": "Output EPCs for TransformationEvent (stored as JSON verbatim)." }, "originLocation": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "eudrPlotId": { "type": "string" } }, "description": "Geographic origin; used only to derive a default `readPoint` (`geo:,`) when `readPoint` is absent. `latitude`/`longitude` are required here for correct usage but NOT enforced server-side: an `originLocation` missing them is not rejected — the derived `readPoint` is then silently persisted as the malformed literal `geo:undefined,undefined`." }, "responsibleOperatorDid": { "type": "string", "description": "DID of the responsible economic operator. Fallback for `bizLocation`, and (only when `issuer` is absent) for the operator-scope check on operator-scoped API keys." } } } ``` ## Used by - schema [UntpEventCredential](/schemas/UntpEventCredential.md) ================================================================================ # FILE: /okf/schemas/UntpEventProof.md ================================================================================ --- type: Schema title: UntpEventProof description: Credential proof. resource: https://opendpp-node.eu/openapi.json#/components/schemas/UntpEventProof tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Credential proof. MUST be a conformant W3C `DataIntegrityProof` with `cryptosuite: "ecdsa-jcs-2019"` and a multibase base58btc (`z…`) `proofValue`. Verified (ECDSA P-256, IEEE-P1363 raw r‖s) over `sha256(JCS(proof options)) ‖ sha256(JCS(credential without proof))` — RFC 8785 JCS canonicalization, a conformant W3C Data Integrity suite. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `type` | string | yes | MUST be DataIntegrityProof. | | `cryptosuite` | string | yes | MUST be ecdsa-jcs-2019 (RFC 8785 JCS). | | `created` | string | no | — | | `proofPurpose` | string | no | e.g. assertionMethod. | | `verificationMethod` | — | no | Either a key-identifier string or an embedded object carrying an x5c certificate chain. | | `proofValue` | string | yes | Multibase base58btc (z…) ecdsa-jcs-2019 signature. | ## JSON Schema ```json { "type": "object", "description": "Credential proof. MUST be a conformant W3C `DataIntegrityProof` with `cryptosuite: \"ecdsa-jcs-2019\"` and a multibase base58btc (`z…`) `proofValue`. Verified (ECDSA P-256, IEEE-P1363 raw r‖s) over `sha256(JCS(proof options)) ‖ sha256(JCS(credential without proof))` — RFC 8785 JCS canonicalization, a conformant W3C Data Integrity suite.", "required": [ "type", "cryptosuite", "proofValue" ], "properties": { "type": { "type": "string", "const": "DataIntegrityProof", "description": "MUST be `DataIntegrityProof`." }, "cryptosuite": { "type": "string", "const": "ecdsa-jcs-2019", "description": "MUST be `ecdsa-jcs-2019` (RFC 8785 JCS)." }, "created": { "type": "string", "format": "date-time" }, "proofPurpose": { "type": "string", "description": "e.g. `assertionMethod`." }, "verificationMethod": { "oneOf": [ { "type": "string", "description": "Public-key identifier / DID URL." }, { "$ref": "#/components/schemas/UntpVerificationMethod" } ], "description": "Either a key-identifier string or an embedded object carrying an `x5c` certificate chain." }, "proofValue": { "type": "string", "description": "Multibase base58btc (`z…`) ecdsa-jcs-2019 signature. Stored verbatim with the event." } } } ``` ## Used by - schema [UntpEventCredential](/schemas/UntpEventCredential.md) ================================================================================ # FILE: /okf/schemas/UntpVerificationMethod.md ================================================================================ --- type: Schema title: UntpVerificationMethod description: Embedded verification-method object. resource: https://opendpp-node.eu/openapi.json#/components/schemas/UntpVerificationMethod tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Embedded verification-method object. The `x5c` chain (base64 DER, leaf first) is honoured ONLY when the node has trust anchors configured, every certificate is currently valid, each link verifies against the next, the top is anchored, and the leaf attests the credential issuer — otherwise it is ignored and the registered tenant key is used instead. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | no | — | | `type` | string | no | — | | `controller` | string | no | — | | `x5c` | array | no | X.509 certificate chain, base64 DER, leaf first. | ## JSON Schema ```json { "type": "object", "description": "Embedded verification-method object. The `x5c` chain (base64 DER, leaf first) is honoured ONLY when the node has trust anchors configured, every certificate is currently valid, each link verifies against the next, the top is anchored, and the leaf attests the credential issuer — otherwise it is ignored and the registered tenant key is used instead.", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "controller": { "type": "string" }, "x5c": { "type": "array", "items": { "type": "string" }, "description": "X.509 certificate chain, base64 DER, leaf first." } } } ``` ## Used by - schema [UntpEventProof](/schemas/UntpEventProof.md) ================================================================================ # FILE: /okf/schemas/UpdateOperatorRequest.md ================================================================================ --- type: Schema title: UpdateOperatorRequest description: Both fields are optional. resource: https://opendpp-node.eu/openapi.json#/components/schemas/UpdateOperatorRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Both fields are optional. Values must be non-empty strings after trimming; anything else (missing, non-string, whitespace-only) is silently ignored. `regId` and `regIdScheme` cannot be changed. An omitted body or an empty object `{}` is accepted and returns the unchanged row. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `name` | string | no | New display name (trimmed). | | `role` | string | no | New supply-chain role, free text (trimmed) — e.g. MANUFACTURER, IMPORTER, RETAILER. | ## JSON Schema ```json { "type": "object", "description": "Both fields are optional. Values must be non-empty strings after trimming; anything else (missing, non-string, whitespace-only) is silently ignored. `regId` and `regIdScheme` cannot be changed. An omitted body or an empty object `{}` is accepted and returns the unchanged row.", "properties": { "name": { "type": "string", "description": "New display name (trimmed)." }, "role": { "type": "string", "description": "New supply-chain role, free text (trimmed) — e.g. `MANUFACTURER`, `IMPORTER`, `RETAILER`." } } } ``` ## Used by - [updateOperator](/operations/updateOperator.md) (`PATCH /api/v1/operators/{id}`) ================================================================================ # FILE: /okf/schemas/UpdateOperatorResponse.md ================================================================================ --- type: Schema title: UpdateOperatorResponse description: The economic operator as stored after the update. resource: https://opendpp-node.eu/openapi.json#/components/schemas/UpdateOperatorResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The economic operator as stored after the update. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `operator` | [OperatorRow](/schemas/OperatorRow.md) | yes | — | ## JSON Schema ```json { "description": "The economic operator as stored after the update.", "type": "object", "required": [ "success", "operator" ], "properties": { "success": { "type": "boolean", "const": true }, "operator": { "$ref": "#/components/schemas/OperatorRow" } } } ``` ## Used by - [updateOperator](/operations/updateOperator.md) (`PATCH /api/v1/operators/{id}`) ================================================================================ # FILE: /okf/schemas/ValidationErrorItem.md ================================================================================ --- type: Schema title: ValidationErrorItem description: One field-level finding from ESPR category validation. resource: https://opendpp-node.eu/openapi.json#/components/schemas/ValidationErrorItem tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One field-level finding from ESPR category validation. `path` uses dot/bracket notation into the metadata object (e.g. `materialComposition[0].percentage`). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `path` | string | yes | Dot/bracket path of the offending metadata field. | | `message` | string | yes | Technical validation message. | | `friendlyMessage` | string | no | Localized, human-friendly explanation (language from ?lang= or Accept-Language; 28 languages, default en). | ## JSON Schema ```json { "type": "object", "description": "One field-level finding from ESPR category validation. `path` uses dot/bracket notation into the metadata object (e.g. `materialComposition[0].percentage`).", "required": [ "path", "message" ], "properties": { "path": { "type": "string", "description": "Dot/bracket path of the offending metadata field." }, "message": { "type": "string", "description": "Technical validation message." }, "friendlyMessage": { "type": "string", "description": "Localized, human-friendly explanation (language from `?lang=` or `Accept-Language`; 28 languages, default `en`)." } } } ``` ## Used by - schema [PassportCreateValidationError](/schemas/PassportCreateValidationError.md) - schema [AasIngestValidationError](/schemas/AasIngestValidationError.md) - schema [PassportIngestCreated](/schemas/PassportIngestCreated.md) - schema [PassportValidateOnlyResult](/schemas/PassportValidateOnlyResult.md) - schema [PassportValidateOnlyError](/schemas/PassportValidateOnlyError.md) - schema [AasIngestCreated](/schemas/AasIngestCreated.md) - schema [PassportUpdateValidationError](/schemas/PassportUpdateValidationError.md) ================================================================================ # FILE: /okf/schemas/WebhookDeliveriesResponse.md ================================================================================ --- type: Schema title: WebhookDeliveriesResponse description: Recent webhook delivery attempts for a subscription, newest first, for debugging endpoint failures. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookDeliveriesResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Recent webhook delivery attempts for a subscription, newest first, for debugging endpoint failures. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `count` | integer | yes | — | | `deliveries` | array<[WebhookDeliveryRow](/schemas/WebhookDeliveryRow.md)> | yes | — | ## JSON Schema ```json { "description": "Recent webhook delivery attempts for a subscription, newest first, for debugging endpoint failures.", "type": "object", "required": [ "success", "count", "deliveries" ], "properties": { "success": { "type": "boolean", "const": true }, "count": { "type": "integer" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryRow" } } } } ``` ## Used by - [listWebhookDeliveries](/operations/listWebhookDeliveries.md) (`GET /api/v1/webhooks/deliveries`) ================================================================================ # FILE: /okf/schemas/WebhookDeliveryRow.md ================================================================================ --- type: Schema title: WebhookDeliveryRow description: One outbox delivery record (event-level). resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookDeliveryRow tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- One outbox delivery record (event-level). The payload is not included. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | yes | Outbox record id. | | `event` | string | yes | Event type, e.g. passport.sealed. | | `status` | string | yes | Overall delivery state. | | `retryCount` | integer | yes | Failed attempts so far (0–5). | | `lastAttempt` | string,null | yes | Timestamp of the most recent attempt, or null if never attempted. | | `nextRetryAt` | string,null | yes | When the next retry is eligible (null if delivered or dead-lettered). | | `errorMessage` | string,null | yes | Joined per-endpoint error text from the last failed attempt, or null. | | `createdAt` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "One outbox delivery record (event-level). The payload is not included.", "required": [ "id", "event", "status", "retryCount", "lastAttempt", "nextRetryAt", "errorMessage", "createdAt" ], "properties": { "id": { "type": "string", "description": "Outbox record id." }, "event": { "type": "string", "description": "Event type, e.g. `passport.sealed`." }, "status": { "type": "string", "enum": [ "PENDING", "DELIVERED", "FAILED" ], "description": "Overall delivery state. FAILED after 5 exhausted attempts (dead-lettered)." }, "retryCount": { "type": "integer", "description": "Failed attempts so far (0–5)." }, "lastAttempt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent attempt, or null if never attempted." }, "nextRetryAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the next retry is eligible (null if delivered or dead-lettered)." }, "errorMessage": { "type": [ "string", "null" ], "description": "Joined per-endpoint error text from the last failed attempt, or null." }, "createdAt": { "type": "string", "format": "date-time" } } } ``` ## Used by - schema [WebhookDeliveriesResponse](/schemas/WebhookDeliveriesResponse.md) ================================================================================ # FILE: /okf/schemas/WebhookEnvelope.md ================================================================================ --- type: Schema title: WebhookEnvelope description: The signed body of every webhook delivery. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookEnvelope tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The signed body of every webhook delivery. `data` is the public (redacted) JSON-LD passport document; `type` is the concrete event name (also in the `X-OpenDPP-Event` header); `id` is the stable delivery id (also in the `X-OpenDPP-Delivery` header) and is CONSTANT across all retries of the same event, so deduplicate on it for exactly-once processing; `created` is the event time (stable across retries, distinct from the per-attempt `X-OpenDPP-Timestamp`). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | yes | Stable delivery id; mirrors the X-OpenDPP-Delivery header; constant across retries. | | `type` | string | yes | Concrete event type (also in the X-OpenDPP-Event header). | | `created` | string | yes | Event creation/enqueue time (stable across retries). | | `data` | [PublicPassportJsonLd](/schemas/PublicPassportJsonLd.md) | yes | The public (redacted) JSON-LD passport document — the same shape resolvers return. | ## JSON Schema ```json { "type": "object", "description": "The signed body of every webhook delivery. `data` is the public (redacted) JSON-LD passport document; `type` is the concrete event name (also in the `X-OpenDPP-Event` header); `id` is the stable delivery id (also in the `X-OpenDPP-Delivery` header) and is CONSTANT across all retries of the same event, so deduplicate on it for exactly-once processing; `created` is the event time (stable across retries, distinct from the per-attempt `X-OpenDPP-Timestamp`).", "required": [ "id", "type", "created", "data" ], "properties": { "id": { "type": "string", "description": "Stable delivery id; mirrors the `X-OpenDPP-Delivery` header; constant across retries." }, "type": { "type": "string", "enum": [ "passport.ingested", "passport.updated", "passport.sealed", "passport.recalled", "passport.status_updated" ], "description": "Concrete event type (also in the `X-OpenDPP-Event` header). Never the `*` filter value." }, "created": { "type": "string", "format": "date-time", "description": "Event creation/enqueue time (stable across retries)." }, "data": { "$ref": "#/components/schemas/PublicPassportJsonLd", "description": "The public (redacted) JSON-LD passport document — the same shape resolvers return." } } } ``` ================================================================================ # FILE: /okf/schemas/WebhookEventFilter.md ================================================================================ --- type: Schema title: WebhookEventFilter description: Subscribable event filter values. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookEventFilter tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Subscribable event filter values. `*` matches every emitted event. `passport.status_updated` (decommission/reactivate) and `passport.updated` (in-place edit of a published passport) are now first-class subscribable filters. ## JSON Schema ```json { "type": "string", "enum": [ "passport.ingested", "passport.updated", "passport.sealed", "passport.recalled", "passport.status_updated", "*" ], "description": "Subscribable event filter values. `*` matches every emitted event. `passport.status_updated` (decommission/reactivate) and `passport.updated` (in-place edit of a published passport) are now first-class subscribable filters." } ``` ## Used by - schema [WebhookSubscriptionCreateRequest](/schemas/WebhookSubscriptionCreateRequest.md) - schema [WebhookSubscriptionRow](/schemas/WebhookSubscriptionRow.md) - schema [WebhookSubscriptionUpdateRequest](/schemas/WebhookSubscriptionUpdateRequest.md) ================================================================================ # FILE: /okf/schemas/WebhookSecretRotateResponse.md ================================================================================ --- type: Schema title: WebhookSecretRotateResponse description: Confirmation that a subscription's HMAC signing secret was rotated; the new secret is returned once and cannot be retrieved again. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookSecretRotateResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Confirmation that a subscription's HMAC signing secret was rotated; the new secret is returned once and cannot be retrieved again. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | — | | `subscription` | [WebhookSubscriptionWithSecret](/schemas/WebhookSubscriptionWithSecret.md) | yes | — | ## JSON Schema ```json { "description": "Confirmation that a subscription's HMAC signing secret was rotated; the new secret is returned once and cannot be retrieved again.", "type": "object", "required": [ "success", "message", "subscription" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "subscription": { "$ref": "#/components/schemas/WebhookSubscriptionWithSecret" } } } ``` ## Used by - [rotateWebhookSecret](/operations/rotateWebhookSecret.md) (`POST /api/v1/webhooks/subscriptions/{id}/rotate-secret`) ================================================================================ # FILE: /okf/schemas/WebhookSubscriptionCreateRequest.md ================================================================================ --- type: Schema title: WebhookSubscriptionCreateRequest description: An endpoint to receive webhook deliveries, and the event types it subscribes to. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookSubscriptionCreateRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- An endpoint to receive webhook deliveries, and the event types it subscribes to. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `url` | string | yes | Absolute http(s) endpoint URL of your receiver (e.g. a PLM/ERP integration endpoint). | | `events` | array<[WebhookEventFilter](/schemas/WebhookEventFilter.md)> | yes | Non-empty list of event filters. | ## JSON Schema ```json { "description": "An endpoint to receive webhook deliveries, and the event types it subscribes to.", "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Absolute http(s) endpoint URL of your receiver (e.g. a PLM/ERP integration endpoint). DNS-resolved and SSRF-guarded at registration: malformed URLs, loopback, private (RFC 1918/CGNAT), link-local/cloud-metadata, multicast, and equivalent IPv6 ranges are rejected with 400. Redirects are never followed at delivery time." }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEventFilter" }, "description": "Non-empty list of event filters. Any value outside the allowed set is rejected with 400." } } } ``` ## Used by - [createWebhookSubscription](/operations/createWebhookSubscription.md) (`POST /api/v1/webhooks/subscriptions`) ================================================================================ # FILE: /okf/schemas/WebhookSubscriptionCreateResponse.md ================================================================================ --- type: Schema title: WebhookSubscriptionCreateResponse description: Confirmation that a webhook subscription was created, carrying the stored subscription. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookSubscriptionCreateResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Confirmation that a webhook subscription was created, carrying the stored subscription. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | — | | `subscription` | [WebhookSubscriptionWithSecret](/schemas/WebhookSubscriptionWithSecret.md) | yes | — | ## JSON Schema ```json { "description": "Confirmation that a webhook subscription was created, carrying the stored subscription.", "type": "object", "required": [ "success", "message", "subscription" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Webhook subscription registered successfully" }, "subscription": { "$ref": "#/components/schemas/WebhookSubscriptionWithSecret" } } } ``` ## Used by - [createWebhookSubscription](/operations/createWebhookSubscription.md) (`POST /api/v1/webhooks/subscriptions`) ================================================================================ # FILE: /okf/schemas/WebhookSubscriptionDeleteResponse.md ================================================================================ --- type: Schema title: WebhookSubscriptionDeleteResponse description: Confirmation that a webhook subscription was deleted. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookSubscriptionDeleteResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Confirmation that a webhook subscription was deleted. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | yes | — | ## JSON Schema ```json { "description": "Confirmation that a webhook subscription was deleted.", "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Webhook subscription successfully deleted" } } } ``` ## Used by - [deleteWebhookSubscription](/operations/deleteWebhookSubscription.md) (`DELETE /api/v1/webhooks/subscriptions/{id}`) ================================================================================ # FILE: /okf/schemas/WebhookSubscriptionListResponse.md ================================================================================ --- type: Schema title: WebhookSubscriptionListResponse description: The calling workspace's webhook subscriptions. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookSubscriptionListResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The calling workspace's webhook subscriptions. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `subscriptions` | array<[WebhookSubscriptionRow](/schemas/WebhookSubscriptionRow.md)> | yes | — | ## JSON Schema ```json { "description": "The calling workspace's webhook subscriptions.", "type": "object", "required": [ "success", "subscriptions" ], "properties": { "success": { "type": "boolean", "const": true }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionRow" } } } } ``` ## Used by - [listWebhookSubscriptions](/operations/listWebhookSubscriptions.md) (`GET /api/v1/webhooks/subscriptions`) ================================================================================ # FILE: /okf/schemas/WebhookSubscriptionRow.md ================================================================================ --- type: Schema title: WebhookSubscriptionRow description: A webhook subscription row with the HMAC signing secret stripped (it is shown exactly once, in the 201 create response). resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookSubscriptionRow tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- A webhook subscription row with the HMAC signing `secret` stripped (it is shown exactly once, in the 201 create response). ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | string | yes | Subscription id. | | `tenantId` | string | yes | Owning workspace (tenant) id. | | `url` | string | yes | Receiver endpoint URL. | | `events` | array<[WebhookEventFilter](/schemas/WebhookEventFilter.md)> | yes | Event filters this subscription matches (validated at creation). | | `isActive` | boolean | yes | true while the subscription receives deliveries; only active subscriptions are delivered to. | | `createdAt` | string | yes | — | | `updatedAt` | string | yes | — | ## JSON Schema ```json { "type": "object", "description": "A webhook subscription row with the HMAC signing `secret` stripped (it is shown exactly once, in the 201 create response).", "required": [ "id", "tenantId", "url", "events", "isActive", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Subscription id." }, "tenantId": { "type": "string", "description": "Owning workspace (tenant) id." }, "url": { "type": "string", "format": "uri", "description": "Receiver endpoint URL." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventFilter" }, "description": "Event filters this subscription matches (validated at creation)." }, "isActive": { "type": "boolean", "description": "`true` while the subscription receives deliveries; only active subscriptions are delivered to. Toggle with `PATCH /api/v1/webhooks/subscriptions/{id}` (`isActive`) to pause/resume without deleting." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } ``` ## Used by - schema [WebhookSubscriptionWithSecret](/schemas/WebhookSubscriptionWithSecret.md) - schema [WebhookSubscriptionListResponse](/schemas/WebhookSubscriptionListResponse.md) - schema [WebhookSubscriptionUpdateResponse](/schemas/WebhookSubscriptionUpdateResponse.md) ================================================================================ # FILE: /okf/schemas/WebhookSubscriptionUpdateRequest.md ================================================================================ --- type: Schema title: WebhookSubscriptionUpdateRequest description: All fields optional; include only what you want to change. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookSubscriptionUpdateRequest tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- All fields optional; include only what you want to change. The secret is not editable here. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `url` | string | no | New receiver URL. | | `events` | array<[WebhookEventFilter](/schemas/WebhookEventFilter.md)> | no | Replacement (non-empty) event-filter set. | | `isActive` | boolean | no | Pause (false) or resume (true) deliveries. | ## JSON Schema ```json { "type": "object", "description": "All fields optional; include only what you want to change. The secret is not editable here.", "properties": { "url": { "type": "string", "format": "uri", "description": "New receiver URL. Re-validated by the SSRF guard." }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEventFilter" }, "description": "Replacement (non-empty) event-filter set." }, "isActive": { "type": "boolean", "description": "Pause (`false`) or resume (`true`) deliveries." } } } ``` ## Used by - [updateWebhookSubscription](/operations/updateWebhookSubscription.md) (`PATCH /api/v1/webhooks/subscriptions/{id}`) ================================================================================ # FILE: /okf/schemas/WebhookSubscriptionUpdateResponse.md ================================================================================ --- type: Schema title: WebhookSubscriptionUpdateResponse description: The webhook subscription as stored after the update. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookSubscriptionUpdateResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The webhook subscription as stored after the update. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `message` | string | no | Present when a change was applied ("Webhook subscription updated"); absent when the body had no recognized fields. | | `subscription` | [WebhookSubscriptionRow](/schemas/WebhookSubscriptionRow.md) | yes | — | ## JSON Schema ```json { "description": "The webhook subscription as stored after the update.", "type": "object", "required": [ "success", "subscription" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "Present when a change was applied (`\"Webhook subscription updated\"`); absent when the body had no recognized fields." }, "subscription": { "$ref": "#/components/schemas/WebhookSubscriptionRow" } } } ``` ## Used by - [updateWebhookSubscription](/operations/updateWebhookSubscription.md) (`PATCH /api/v1/webhooks/subscriptions/{id}`) ================================================================================ # FILE: /okf/schemas/WebhookSubscriptionWithSecret.md ================================================================================ --- type: Schema title: WebhookSubscriptionWithSecret description: The full subscription row as returned ONLY by the 201 create response — includes the HMAC-SHA256 signing secret. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookSubscriptionWithSecret tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The full subscription row as returned ONLY by the 201 create response — includes the HMAC-SHA256 signing secret. ## JSON Schema ```json { "description": "The full subscription row as returned ONLY by the 201 create response — includes the HMAC-SHA256 signing secret.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionRow" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "pattern": "^whsec_[0-9a-f]{32}$", "description": "Server-generated HMAC-SHA256 signing key (`whsec_` + 32 lowercase hex chars). Shown ONCE — here and in the `rotate-secret` response only; the list endpoint strips it. The FULL string, including the `whsec_` prefix, is the HMAC key for delivery signatures. Rotate it with `POST /api/v1/webhooks/subscriptions/{id}/rotate-secret`." } } } ] } ``` ## Used by - schema [WebhookSubscriptionCreateResponse](/schemas/WebhookSubscriptionCreateResponse.md) - schema [WebhookSecretRotateResponse](/schemas/WebhookSecretRotateResponse.md) ================================================================================ # FILE: /okf/schemas/WebhookTestResult.md ================================================================================ --- type: Schema title: WebhookTestResult description: The outcome of delivering a signed sample event to a subscription's endpoint right now. resource: https://opendpp-node.eu/openapi.json#/components/schemas/WebhookTestResult tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The outcome of delivering a signed sample event to a subscription's endpoint right now. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | The request was processed (NOT whether the receiver accepted it — see delivered). | | `event` | string | yes | The event type sent. | | `url` | string | yes | The receiver URL the test was sent to. | | `delivered` | boolean | yes | true if the receiver returned a 2xx within the 5s timeout. | | `statusCode` | integer,null | yes | The receiver's HTTP status, or null on a transport/SSRF error. | | `error` | string,null | yes | Transport/SSRF error message when delivery failed, else null. | ## JSON Schema ```json { "description": "The outcome of delivering a signed sample event to a subscription's endpoint right now.", "type": "object", "required": [ "success", "event", "url", "delivered", "statusCode", "error" ], "properties": { "success": { "type": "boolean", "const": true, "description": "The request was processed (NOT whether the receiver accepted it — see `delivered`)." }, "event": { "type": "string", "description": "The event type sent." }, "url": { "type": "string", "format": "uri", "description": "The receiver URL the test was sent to." }, "delivered": { "type": "boolean", "description": "`true` if the receiver returned a 2xx within the 5s timeout." }, "statusCode": { "type": [ "integer", "null" ], "description": "The receiver's HTTP status, or null on a transport/SSRF error." }, "error": { "type": [ "string", "null" ], "description": "Transport/SSRF error message when delivery failed, else null." } } } ``` ## Used by - [testWebhookSubscription](/operations/testWebhookSubscription.md) (`POST /api/v1/webhooks/subscriptions/{id}/test`) ================================================================================ # FILE: /okf/schemas/WhoamiResponse.md ================================================================================ --- type: Schema title: WhoamiResponse description: "The calling credential's identity: its workspace, the resolved auth principal and permissions, and active-passport usage against the plan quota." resource: https://opendpp-node.eu/openapi.json#/components/schemas/WhoamiResponse tags: - schema generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- The calling credential's identity: its workspace, the resolved auth principal and permissions, and active-passport usage against the plan quota. ## Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `success` | boolean | yes | — | | `tenant` | object | yes | — | | `auth` | object | yes | — | | `usage` | object | yes | — | ## JSON Schema ```json { "description": "The calling credential's identity: its workspace, the resolved auth principal and permissions, and active-passport usage against the plan quota.", "type": "object", "required": [ "success", "tenant", "auth", "usage" ], "properties": { "success": { "type": "boolean", "const": true }, "tenant": { "type": "object", "required": [ "id", "name", "subdomain", "tier", "subscriptionStatus" ], "properties": { "id": { "type": "string", "description": "Workspace (tenant) id." }, "name": { "type": "string", "description": "Workspace company name." }, "subdomain": { "type": [ "string", "null" ], "description": "Workspace subdomain (`.opendpp-node.eu`), or null if none is assigned." }, "tier": { "type": "string", "description": "Subscription tier (e.g. `pilot`, `micro`, `starter`, `growth`, `scale`, `enterprise`)." }, "subscriptionStatus": { "type": [ "string", "null" ], "description": "Billing status string (e.g. `active`, `past_due`). When not `active`, write operations may return `402`. No amounts or processor identifiers are exposed." } } }, "auth": { "type": "object", "required": [ "role", "permissions", "isApiKeySession", "operatorId" ], "properties": { "role": { "type": "string", "description": "The principal's role." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Effective permission strings, re-derived server-side from the role (never trusted from the token). May include wildcards like `operator:*`." }, "isApiKeySession": { "type": "boolean", "description": "`true` when authenticated with an API key, `false` for a session JWT." }, "operatorId": { "type": [ "string", "null" ], "description": "The economic operator this credential is scoped to, or `null` for a workspace-wide key. A scoped key's writes and reads are restricted to this operator." } } }, "usage": { "type": "object", "required": [ "activePassports", "passportLimit" ], "properties": { "activePassports": { "type": "integer", "description": "Active (non-draft, non-archived) passports counted against the quota — operator-scoped for a scoped key." }, "passportLimit": { "type": [ "integer", "null" ], "description": "Tier passport quota, or `null` for an unlimited tier." } } } } } ``` ## Used by - [whoami](/operations/whoami.md) (`GET /api/v1/whoami`) ================================================================================ # FILE: /okf/webhooks/index.md ================================================================================ # Webhook events * [passport.ingested](passport.ingested.md) - Sent when a passport becomes active for the first time: a non-draft POST /api/v1/passports create, the first publish of a draft via PUT /ap… * [passport.recalled](passport.recalled.md) - Sent when PUT /api/v1/passports/{id}/status transitions a passport to RECALLED, transactionally with the status write. * [passport.sealed](passport.sealed.md) - Sent when a passport is sealed via POST /api/v1/passports/{id}/seal, transactionally with the seal write. * [passport.status_updated](passport.status_updated.md) - Sent when PUT /api/v1/passports/{id}/status performs a non-recall transition: decommissioning (DECOMMISSIONED, which also sets retentionUnt… * [passport.updated](passport.updated.md) - Sent when an already-published (non-draft) passport's content is edited in place via PUT /api/v1/passports/{id}, transactionally with the u… ================================================================================ # FILE: /okf/webhooks/passport.ingested.md ================================================================================ --- type: Webhook Event title: passport.ingested description: Passport created or first published resource: https://opendpp-node.eu/openapi.json#/webhooks/passport.ingested tags: - webhook - event generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Sent when a passport becomes active for the first time: a non-draft `POST /api/v1/passports` create, the **first publish** of a draft via `PUT /api/v1/passports/{id}`, or each successfully ingested row of `POST /api/v1/passports/bulk`. Draft creation does NOT emit it, non-publish updates and deletes emit nothing, and **AAS ingestion (`POST /api/v1/passports/aas/ingest`) emits no webhook events at all**. The payload is the freshly created passport: `status: "ACTIVE"` with `digitalSeal` and `proof` still `null` (unless a previously sealed draft is re-published). Emission is enqueued transactionally with the passport write (outbox pattern) and delivered asynchronously to every active subscription whose filter contains `passport.ingested` or `*`. **Delivery contract** (sender `User-Agent: OpenDPP-Webhook-Outbox/1.0`): - The body is a JSON **envelope** `{ id, type, created, data }`: `data` is the **public (redacted) JSON-LD passport document**, `type` is the event name (also in the `X-OpenDPP-Event` header), and `id` is the stable delivery id (also in the `X-OpenDPP-Delivery` header, constant across retries). Owner-tier fields (facility street address, restricted metadata values) are never included. The owner-only `facilityDetails` metadata key **always appears with the masked value `[REDACTED - Privileged Access Required]`** — in `metadata`, flattened at top level, and in the `@context` term map — even when the passport never set that key; restricted metadata keys likewise appear masked, with their true leaf hashes preserved in `proof.redactedLeaves` once sealed. - **Success = any HTTP 2xx** returned within the **5-second** timeout. Redirects are **never followed** — a 3xx counts as failure. The response body is ignored. - **Retries:** up to **5 delivery attempts** total. Failed attempts 1–4 schedule the next attempt with exponential backoff — ~1 min, 5 min, 30 min, then 2 h after the previous failure. The **5th failed attempt dead-letters the event** (no further deliveries) and the workspace receives an in-app notification. - **Per-subscription dedup:** endpoints that already returned 2xx are not re-POSTed when the same event is retried for sibling subscriptions. Still treat delivery as at-least-once (a 2xx the sender fails to record can re-deliver), but the **`X-OpenDPP-Delivery`** id is STABLE across retries, so deduplicate on it for exactly-once. - **Signature verification:** compute `HMAC-SHA256(secret, X-OpenDPP-Timestamp + "." + rawBody)` keyed with the FULL `whsec_…` secret (including the prefix), hex-encode lowercase, constant-time-compare with `X-OpenDPP-Signature` (bare hex — no `v1=`/`sha256=` prefix). Verify over the **raw body bytes** before any JSON parsing. Reject timestamps older than ~5 minutes; the timestamp and signature are **re-minted on every retry attempt**, so retried deliveries always carry a fresh, valid pair. ## Delivery Deliveries are HMAC-SHA256-signed `POST` requests with retry/backoff. Subscribe and manage endpoints via the [Webhooks](/tags/webhooks.md) tag. ## Payload Schema: [WebhookEnvelope](/schemas/WebhookEnvelope.md). ================================================================================ # FILE: /okf/webhooks/passport.recalled.md ================================================================================ --- type: Webhook Event title: passport.recalled description: Passport recalled resource: https://opendpp-node.eu/openapi.json#/webhooks/passport.recalled tags: - webhook - event generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Sent when `PUT /api/v1/passports/{id}/status` transitions a passport to `RECALLED`, transactionally with the status write. The payload is the public JSON-LD passport with `status: "RECALLED"` (seal/proof fields reflect whatever state the passport was in when recalled). Delivered to every active subscription whose filter contains `passport.recalled` or `*`. **Delivery contract** (sender `User-Agent: OpenDPP-Webhook-Outbox/1.0`): - The body is a JSON **envelope** `{ id, type, created, data }`: `data` is the **public (redacted) JSON-LD passport document**, `type` is the event name (also in the `X-OpenDPP-Event` header), and `id` is the stable delivery id (also in the `X-OpenDPP-Delivery` header, constant across retries). The owner-only `facilityDetails` metadata key **always appears with the masked value `[REDACTED - Privileged Access Required]`** (in `metadata`, flattened at top level, and in the `@context` term map) even when the passport never set that key; restricted metadata keys likewise appear masked. - **Success = any HTTP 2xx** within the **5-second** timeout. Redirects are **never followed** (3xx = failure). Response body ignored. - **Retries:** up to **5 delivery attempts** total. Failed attempts 1–4 schedule the next attempt ~1 min / 5 min / 30 min / 2 h after the previous failure; the **5th failed attempt dead-letters the event** and the workspace is notified in-app. - **Per-subscription dedup:** endpoints that already returned 2xx are not re-POSTed on retries; still treat delivery as at-least-once, but the **`X-OpenDPP-Delivery`** id is STABLE across retries, so deduplicate on it for exactly-once. - **Signature verification:** `HMAC-SHA256(secret, X-OpenDPP-Timestamp + "." + rawBody)` keyed with the FULL `whsec_…` secret, lowercase hex, constant-time compare against `X-OpenDPP-Signature` (bare hex, no scheme prefix). Verify over the **raw body bytes**; reject >~5 min timestamp skew; timestamp+signature are re-minted per retry attempt. ## Delivery Deliveries are HMAC-SHA256-signed `POST` requests with retry/backoff. Subscribe and manage endpoints via the [Webhooks](/tags/webhooks.md) tag. ## Payload Schema: [WebhookEnvelope](/schemas/WebhookEnvelope.md). ================================================================================ # FILE: /okf/webhooks/passport.sealed.md ================================================================================ --- type: Webhook Event title: passport.sealed description: Passport sealed with an advanced electronic seal resource: https://opendpp-node.eu/openapi.json#/webhooks/passport.sealed tags: - webhook - event generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Sent when a passport is sealed via `POST /api/v1/passports/{id}/seal`, transactionally with the seal write. The payload carries the populated `digitalSeal`, `signingPublicKey`, and the `proof` block: `merkleRoot` always; an `x5c` certificate chain binding the signing key to the tenant's legal identity **when the tenant's signing key has an issued chain**; an **optional** `rfc3161` trusted timestamp; and `redactedLeaves` hashes **when the passport carries masked metadata keys**. Delivered to every active subscription whose filter contains `passport.sealed` or `*`. **Delivery contract** (sender `User-Agent: OpenDPP-Webhook-Outbox/1.0`): - The body is a JSON **envelope** `{ id, type, created, data }`: `data` is the **public (redacted) JSON-LD passport document**, `type` is the event name (also in the `X-OpenDPP-Event` header), and `id` is the stable delivery id (also in the `X-OpenDPP-Delivery` header, constant across retries). The owner-only `facilityDetails` metadata key **always appears with the masked value `[REDACTED - Privileged Access Required]`** (in `metadata`, flattened at top level, and in the `@context` term map) even when the passport never set that key; restricted metadata keys likewise appear masked, with their true leaf hashes in `proof.redactedLeaves`. - **Success = any HTTP 2xx** within the **5-second** timeout. Redirects are **never followed** (3xx = failure). Response body ignored. - **Retries:** up to **5 delivery attempts** total. Failed attempts 1–4 schedule the next attempt ~1 min / 5 min / 30 min / 2 h after the previous failure; the **5th failed attempt dead-letters the event** and the workspace is notified in-app. - **Per-subscription dedup:** endpoints that already returned 2xx are not re-POSTed on retries; still treat delivery as at-least-once, but the **`X-OpenDPP-Delivery`** id is STABLE across retries, so deduplicate on it for exactly-once. - **Signature verification:** `HMAC-SHA256(secret, X-OpenDPP-Timestamp + "." + rawBody)` keyed with the FULL `whsec_…` secret, lowercase hex, constant-time compare against `X-OpenDPP-Signature` (bare hex, no scheme prefix). Verify over the **raw body bytes**; reject >~5 min timestamp skew; timestamp+signature are re-minted per retry attempt. ## Delivery Deliveries are HMAC-SHA256-signed `POST` requests with retry/backoff. Subscribe and manage endpoints via the [Webhooks](/tags/webhooks.md) tag. ## Payload Schema: [WebhookEnvelope](/schemas/WebhookEnvelope.md). ================================================================================ # FILE: /okf/webhooks/passport.status_updated.md ================================================================================ --- type: Webhook Event title: passport.status_updated description: Passport status changed (decommission or reactivation) resource: https://opendpp-node.eu/openapi.json#/webhooks/passport.status_updated tags: - webhook - event generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Sent when `PUT /api/v1/passports/{id}/status` performs a non-recall transition: decommissioning (`DECOMMISSIONED`, which also sets `retentionUntil` and starts the retention clock) or reactivation back to `ACTIVE`. Subscribe to it directly with the `passport.status_updated` filter (or `*`). **Delivery contract** (sender `User-Agent: OpenDPP-Webhook-Outbox/1.0`): - The body is a JSON **envelope** `{ id, type, created, data }`: `data` is the **public (redacted) JSON-LD passport document**, `type` is the event name (also in the `X-OpenDPP-Event` header), and `id` is the stable delivery id (also in the `X-OpenDPP-Delivery` header, constant across retries). The owner-only `facilityDetails` metadata key **always appears with the masked value `[REDACTED - Privileged Access Required]`** (in `metadata`, flattened at top level, and in the `@context` term map) even when the passport never set that key; restricted metadata keys likewise appear masked. - **Success = any HTTP 2xx** within the **5-second** timeout. Redirects are **never followed** (3xx = failure). Response body ignored. - **Retries:** up to **5 delivery attempts** total. Failed attempts 1–4 schedule the next attempt ~1 min / 5 min / 30 min / 2 h after the previous failure; the **5th failed attempt dead-letters the event** and the workspace is notified in-app. - **Per-subscription dedup:** endpoints that already returned 2xx are not re-POSTed on retries; still treat delivery as at-least-once, but the **`X-OpenDPP-Delivery`** id is STABLE across retries, so deduplicate on it for exactly-once. - **Signature verification:** `HMAC-SHA256(secret, X-OpenDPP-Timestamp + "." + rawBody)` keyed with the FULL `whsec_…` secret, lowercase hex, constant-time compare against `X-OpenDPP-Signature` (bare hex, no scheme prefix). Verify over the **raw body bytes**; reject >~5 min timestamp skew; timestamp+signature are re-minted per retry attempt. ## Delivery Deliveries are HMAC-SHA256-signed `POST` requests with retry/backoff. Subscribe and manage endpoints via the [Webhooks](/tags/webhooks.md) tag. ## Payload Schema: [WebhookEnvelope](/schemas/WebhookEnvelope.md). ================================================================================ # FILE: /okf/webhooks/passport.updated.md ================================================================================ --- type: Webhook Event title: passport.updated description: Passport edited in place resource: https://opendpp-node.eu/openapi.json#/webhooks/passport.updated tags: - webhook - event generated: by: process:emit-okf at: 2026-08-17T00:00:00Z --- Sent when an already-published (non-draft) passport's content is edited in place via `PUT /api/v1/passports/{id}`, transactionally with the update write. This is **distinct from first publish** (that emits `passport.ingested`, not this event) and is **never** emitted for sealed passports — in-place edits of a sealed passport are rejected with `403`. The payload is the updated public JSON-LD passport with `status: "ACTIVE"`. Delivered to every active subscription whose filter contains `passport.updated` or `*`. **Delivery contract** (sender `User-Agent: OpenDPP-Webhook-Outbox/1.0`): - The body is a JSON **envelope** `{ id, type, created, data }`: `data` is the **public (redacted) JSON-LD passport document**, `type` is the event name (also in the `X-OpenDPP-Event` header), and `id` is the stable delivery id (also in the `X-OpenDPP-Delivery` header, constant across retries). The owner-only `facilityDetails` metadata key **always appears with the masked value `[REDACTED - Privileged Access Required]`** (in `metadata`, flattened at top level, and in the `@context` term map) even when the passport never set that key; restricted metadata keys likewise appear masked. - **Success = any HTTP 2xx** within the **5-second** timeout. Redirects are **never followed** (3xx = failure). Response body ignored. - **Retries:** up to **5 delivery attempts** total. Failed attempts 1–4 schedule the next attempt ~1 min / 5 min / 30 min / 2 h after the previous failure; the **5th failed attempt dead-letters the event** and the workspace is notified in-app. - **Per-subscription dedup:** endpoints that already returned 2xx are not re-POSTed on retries; still treat delivery as at-least-once, but the **`X-OpenDPP-Delivery`** id is STABLE across retries, so deduplicate on it for exactly-once. - **Signature verification:** `HMAC-SHA256(secret, X-OpenDPP-Timestamp + "." + rawBody)` keyed with the FULL `whsec_…` secret, lowercase hex, constant-time compare against `X-OpenDPP-Signature` (bare hex, no scheme prefix). Verify over the **raw body bytes**; reject >~5 min timestamp skew; timestamp+signature are re-minted per retry attempt. ## Delivery Deliveries are HMAC-SHA256-signed `POST` requests with retry/backoff. Subscribe and manage endpoints via the [Webhooks](/tags/webhooks.md) tag. ## Payload Schema: [WebhookEnvelope](/schemas/WebhookEnvelope.md). ================================================================================ # FILE: /okf/log.md ================================================================================ # Log ## 2026-08-17 **Update** — Knowledge bundle generated for OpenDPP Integration API v1.14.0. For the full per-version API contract history see [`/openapi.json`](https://opendpp-node.eu/openapi.json). ================================================================================ # FILE: /okf/index.md ================================================================================ --- okf_version: "0.2" --- # OpenDPP Integration API — Knowledge Bundle > An OKF (Open Knowledge Format) projection of the public [OpenDPP Integration API](https://opendpp-node.eu/api-reference), for ingestion by AI agents and humans alike. Generated from [`/openapi.json`](https://opendpp-node.eu/openapi.json) (API v1.14.0). # Concepts * [Overview](overview.md) - What the OpenDPP Integration API does, how it is organised, and where to start. * [Log](log.md) - Generation history. # Subdirectories * [guides](guides/index.md) - Curated integration playbooks and references. * [tags](tags/index.md) - One overview per API domain. * [operations](operations/index.md) - One concept per endpoint. * [schemas](schemas/index.md) - One concept per request/response object. * [webhooks](webhooks/index.md) - Lifecycle events you can subscribe to.