Use the DPP Shield REST API

Where the reference is

The API reference at /en/developers lists every operation, generated from the API source, and offers the OpenAPI 3.1 file for download (https://dppshield.com/openapi.json) to import into Postman, Insomnia or a code generator. The base URL is https://api.dppshield.com/api/v1.

Create a key

Send the key as X-API-Key: dpk_… or Authorization: Bearer dpk_…. A key belongs to its organization, so no organization header is needed. It acts as the member who created it, for attribution, and is limited by that member's role and custom role; if that member leaves, the key stops working.

1. Open Settings, API keys (owners and administrators).
2. Name the key after the integration that will use it, choose its scopes and, if you like, an expiry in days.
3. Copy the key: it starts with dpk_ and is shown once; DPP Shield keeps only a hash and the visible prefix.
4. Store it in your secret manager, never in source control.

Scopes

A new key gets dpp:read, dpp:write and compliance:read unless you choose otherwise. Give each integration only what it uses, and one key per integration, so revoking one does not break another.

Available scopes

• dpp:read and dpp:write - passports and their versions.
• compliance:read - validation results.
• products:read and products:write - the catalogue.
• product-models:read and product-models:write - models and variants.
• suppliers:write and documents:write - suppliers and evidence documents.
• claims:read, claims:write and evidence-graph:read - claims and the evidence graph.
• custody:read and custody:write - the chain-of-custody ledger.
• data-mappings:write - integration hub runs.
• identity:read, exports:read and analytics:read - identity checks, CSV exports and analytics.

First calls

These calls cover the usual first integration: read the catalogue, create a product and its passport, save data and validate it.

Common operations

• GET /products lists the catalogue; GET /products/search?q=…&category=…&page=1&pageSize=50 returns a filtered page.
• POST /products creates a product (name, sku, category, gtin…).
• POST /dpp with productId and schemaId (eu-<category>, for example eu-battery) creates a draft passport.
• PUT /dpp/{id} with data saves a new version; send expectedVersion to be refused (409) if someone saved in between.
• POST /dpp/{id}/validate?markets=EU runs validation and returns the findings.
• GET /dpp/search?status=active returns passports by status; GET /public/dpp/{id} reads a published passport without a key.

Rate limits

Requests are counted per organization per hour, with separate budgets for reads and writes set by your plan. Every response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset; over the limit the API answers 429 with Retry-After. Public routes such as passport reads and the GS1 resolver are metered per client address instead.

What a key cannot do

Publishing a passport, deciding a publication override, registering a release in the EU registry and bulk publish, recall or archive are accountable acts. On DPP Shield they need a person who confirmed a second factor in the last 15 minutes, so an API key is refused. Prepare and validate through the API, and let an owner or administrator publish. An organization network allowlist also applies to API keys.

Errors

Errors come back as JSON with a message that names the problem.

Status codes

• 400 - the body or a value failed validation; the message names the field.
• 401 - the key is missing, revoked or expired.
• 403 - the key's scope, its creator's role or a custom role does not allow the operation.
• 404 - the record does not exist in this organization, or lies outside a restricted member's workspaces.
• 409 - the passport changed since the version you sent.
• 429 - the rate limit was reached; wait for Retry-After.