API overview
Four resources, and the relationships between them
Passports describe. Events record. Credentials prove. Resolution serves. Getting those four straight before you start is what keeps an integration from having to be unwound six months in.
- Base path
- /v1
- Format
- JSON over HTTPS
- Auth
- Scoped bearer keys
Definition
How is the Digital Product Passport API structured?
Around four resources. Passports hold the product record and its access policy. Events record what happened to an object, serialised as GS1 EPCIS 2.0. Credentials carry signed claims as W3C Verifiable Credentials. Resolution turns a GS1 Digital Link identifier into the view a caller is entitled to.
Each serialises somebody else’s standard — EPCIS 2.0, VC 2.0 and GS1 Digital Link — so what you build against these endpoints keeps working against a conforming implementation that is not ours.
The model
Which resource answers which question
| Resource | Answers | Standard |
|---|---|---|
| Passport | "What is this product, and who may see which part?" | CIRPASS-aligned model |
| Event | "What happened to this object, where and when?" | GS1 EPCIS 2.0 (JSON-LD) |
| Credential | "Who asserted this, and can I check it myself?" | W3C Verifiable Credentials 2.0 |
| Resolution | "Someone scanned this — what do they get?" | GS1 Digital Link |
Endpoints
The surface, in brief
Passports
Create, read, update and version the product record. Gap reporting against the product group.
Events
Append EPCIS 2.0 events, and query the full history of one object identity.
Credentials
Issue, present, verify and revoke signed claims against a passport.
Resolution
The public read path a scan takes, returning the caller-appropriate tier.
Authentication
Scoped bearer keys, per environment and per capability.
Full reference
Every endpoint, parameter, response shape and error code.
Answers
Frequently asked questions
What are the API’s core resources?
Four. Passports hold the product record and its access policy. Events record what happened to an object, serialised as EPCIS 2.0. Credentials carry signed claims as W3C Verifiable Credentials. Resolution is the read path: a GS1 Digital Link identifier in, the caller-appropriate view out.
When should I write an event rather than update the passport?
Update the passport when you are correcting or completing its description. Write an event when something happened — a step completed, custody transferred, a repair carried out. The rule of thumb is that a passport field answers "what is this?" and an event answers "what happened to it?".
Why is resolution a separate concern from reading a passport?
Because resolution is what a scan does, and it is public, anonymous and cacheable. Reading a passport through the API is authenticated and returns what your key entitles you to. They serve different callers with different guarantees, so conflating them would mean the public path inherits the private path’s cost.
Is the API versioned?
Yes, in the path — everything is under `/v1`. Additive changes ship without a version bump; anything that would break an existing integration gets a new version with an overlap period. Passport records themselves are versioned separately, because a passport outlives any API version it was created under.
Next step
Read the reference next
You now have the model. The reference has the schema, the parameters and the error contract.