Credentials API: Issue, Verify, Status
The HTTP surface of the OpenEPCIS credential issuer and verifier on epc.is, with curl examples for the DID document, OID4VCI metadata, issuance, public retrieval, verification, status lists, the trusted issuer list, audit checkpoints and tier unlock at the resolver.
The credential service on epc.is answers at https://issuer.epc.is. The GS1
Digital Link resolver answers at https://id.epc.is. Read endpoints are
anonymous. Issuing and revoking need a bearer token of your tenant.
Signed Passports explains the concepts behind each call and lists which parts are available, released or in preparation.
Endpoints at a glance
| Method | Path | Access | Purpose |
|---|---|---|---|
GET | /.well-known/did.json | public | Issuer DID document with the verification key |
GET | /.well-known/openid-credential-issuer | public | OID4VCI issuer metadata |
POST | /vc/oid4vci/credential | bearer | OID4VCI credential endpoint for wallets |
POST | /vc/credentials/{configId} | bearer | Administrative issuance |
GET | /vc/credentials/{credentialId} | public | Signed bytes of a Public credential |
POST | /vc/credentials/{credentialId}/revoke | bearer | Permanent revocation |
GET | /vc/status/{listId} | public | Status list credential or token |
POST | /vc/verify?profile= | public | Layered verification |
GET | /.well-known/vc-trusted-issuers[/{tenant}] | public | Signed trusted issuer list (released, not yet on epc.is) |
GET | /.well-known/audit-checkpoints/{tenant} | public | Sealed audit checkpoints (released, not yet on epc.is) |
GET | /vc/oid4vp/request/{sessionId} | wallet | Signed OID4VP request object (released, not yet on epc.is) |
POST | /vc/oid4vp/response/{sessionId} | wallet | OID4VP response, direct_post.jwt (released, not yet on epc.is) |
Errors carry a body that names the reason. A 422 means the request was well formed but the data cannot be signed or found; a 502 means an upstream service failed.
DID document
curl -s https://issuer.epc.is/.well-known/did.json
{
"@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/jws-2020/v1"],
"id": "did:web:issuer.epc.is",
"verificationMethod": [{
"id": "did:web:issuer.epc.is#key-2026-08",
"type": "JsonWebKey2020",
"controller": "did:web:issuer.epc.is",
"publicKeyJwk": { "kty": "EC", "crv": "P-256", "x": "k_8Ex-ND…", "y": "x0o5pWPY…" }
}],
"assertionMethod": ["did:web:issuer.epc.is#key-2026-08"]
}
Every artefact the issuer signs names this method in its kid or
verificationMethod. Keep a copy if you want to verify offline later.
Issuer metadata and credential configurations
curl -s https://issuer.epc.is/.well-known/openid-credential-issuer
The document names the credential endpoint, the authorisation server
(https://auth.epc.is/realms/platform) and every credential configuration with
its OID4VCI format:
| Configuration | Format | Type |
|---|---|---|
dpp-battery, dpp-textile, dpp-electronics, dpp-eudr, dpp-cpr, dpp-ppwr, dpp-iron-steel, dpp-detergent, dpp-fsma204 | ldp_vc | oec:DigitalProductPassport |
dpp-battery-tiered | jwt_vc_json | oec:DigitalProductPassport, one credential per access tier |
org-identity | ldp_vc | DigitalIdentityAnchor (UNTP), revocable |
epcis-event | ldp_vc | EPCIS event credential, subject by reference with the CBV event hash |
To list the configuration ids:
curl -s https://issuer.epc.is/.well-known/openid-credential-issuer \
| python3 -c 'import json,sys; print("\n".join(json.load(sys.stdin)["credential_configurations_supported"]))'
Issuing a credential
Issuance needs an access token of your tenant from the epc.is Keycloak realm. API Reference: Authenticating shows how to get a session token or a long-lived offline token.
For a passport, the subject is the full GS1 Digital Link URI of the product. The host must be a platform host or a verified resolver domain of your tenant.
From a wallet (OID4VCI). Field names follow the specification:
curl -s -X POST https://issuer.epc.is/vc/oid4vci/credential \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"credential_configuration_id": "dpp-battery",
"subject_id": "https://id.epc.is/01/09521002005004"
}'
{ "credential": "<the signed credential>" }
A request with a proof is refused with invalid_proof: this issuer does not
bind credentials to a holder key. Errors use the OAuth shape
{"error": "...", "error_description": "..."}.
From an integration (administrative). Same pipeline, with the stored credential id and media type in the answer:
curl -s -X POST https://issuer.epc.is/vc/credentials/dpp-battery \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{ "subjectId": "https://id.epc.is/01/09521002005004" }'
{
"credentialId": "urn:uuid:…",
"format": "VC_LD_DATA_INTEGRITY",
"mediaType": "application/vc+ld+json",
"credential": "…",
"slices": null
}
For dpp-battery-tiered, slices lists the credential per access tier.
| Status | Meaning |
|---|---|
| 200 | Issued |
| 403 | The token names no tenant, or the subject host is not yours (reason in the body) |
| 404 | Unknown configuration id |
| 422 | The subject source has no such record, or the credential would not be verifiable elsewhere |
| 503 | Issuance is disabled on this instance (no signing key) |
Retrieving a credential
Public credentials are dereferenceable without authentication. The answer is the stored signed artefact under its media type, never a re-rendering:
curl -s https://issuer.epc.is/vc/credentials/<credentialId>
Credentials above the Public tier answer 404 here.
Revoking a credential
curl -s -X POST https://issuer.epc.is/vc/credentials/<credentialId>/revoke \
-H "Authorization: Bearer $TOKEN"
{ "credentialId": "urn:uuid:…", "revoked": true, "error": null }
Revocation is permanent and idempotent. A credential issued without a status slot answers 409, and a credential of another tenant answers 404.
Status lists
The credentialStatus entry of a revocable credential points at its list:
curl -s -D - https://issuer.epc.is/vc/status/<listId>
The list is served anonymously as application/vc+jwt (W3C Bitstring Status
List) or application/statuslist+jwt (IETF Token Status List), with
Cache-Control: public, max-age=300.
Verifying a credential
Pass the credential as a string (compact JWS, SD-JWT, JSON-LD text) or as a
JSON-LD object. The profile parameter selects the policy: self (default),
untp, gs1 or espr-authority. This example fetches a Data Integrity
credential and posts it as an object:
curl -s https://issuer.epc.is/vc/credentials/<credentialId> \
| python3 -c 'import json,sys; print(json.dumps({"credential": json.load(sys.stdin)}))' \
| curl -s -X POST 'https://issuer.epc.is/vc/verify?profile=self' \
-H 'Content-Type: application/json' --data @-
{
"valid": true,
"errors": [],
"issuer": "did:web:issuer.epc.is",
"verificationMethod": "did:web:issuer.epc.is#key-2026-08",
"policy": "self",
"stages": {
"ENVELOPE": "PASS",
"PROOF": "PASS",
"CONTROLLER_BINDING": "PASS",
"VALIDITY": "PASS",
"STATUS": "NOT_APPLICABLE",
"TRUST_ROOT": "NOT_APPLICABLE",
"AUTHORITY": "NOT_APPLICABLE"
},
"assurance": "NONE"
}
valid is the policy decision; stages keeps "signature valid but revoked"
apart from "issuer unknown". A missing body answers 400 with the expected shape,
and an unknown profile answers 400 with the list of profiles.
You do not have to trust our verifier. Any Data Integrity verifier that resolves
did:web can check the same credential, because the DID document and the
contexts are public.
Trusted issuer list
Released, not yet answered by issuer.epc.is. The call is:
curl -s https://issuer.epc.is/.well-known/vc-trusted-issuers
curl -s https://issuer.epc.is/.well-known/vc-trusted-issuers/<tenant>
The answer is application/jwt, a compact JWS with typ: trusted-issuers+jwt.
To read the payload:
curl -s https://issuer.epc.is/.well-known/vc-trusted-issuers \
| python3 -c 'import sys,base64,json; p=sys.stdin.read().split(".")[1]; print(json.dumps(json.loads(base64.urlsafe_b64decode(p+"="*(-len(p)%4))),indent=2))'
{
"iss": "did:web:issuer.epc.is",
"iat": 1792707756,
"exp": 1792711356,
"ver": 1792707756954,
"issuers": [
{ "id": "did:web:issuer.partner.example", "kind": "did", "tenant": "…",
"scopes": ["https://id.gs1.org/01/0401234"], "status": "active" }
]
}
Check the signature against the key in did.json whose id equals the header
kid, reject an expired list, and refuse a ver lower than one you have seen.
An unknown tenant receives a valid, empty list.
Audit checkpoints
Released, not yet answered by issuer.epc.is. The tenant is a chain key:
gln-<GLN13>, grp-<tenant group> or platform.
curl -s https://issuer.epc.is/.well-known/audit-checkpoints/gln-<GLN13>
{ "tenant": "gln-…", "checkpoints": ["<jws>", "<jws>"] }
Each checkpoint decodes to a payload like this:
{
"tenant": "grp-…",
"seq": 878,
"head": "f4888da4700b4a43c15df2e3bf79e1228140f886038ccea0c2bfa57f746e2377",
"issuedAt": "2026-10-22T18:05:07.998Z",
"kid": "did:web:issuer.epc.is#key-2026-08",
"iss": "did:web:issuer.epc.is"
}
A seal verifies against did.json. With an export of the entries from your
tenant you can recompute each hash = sha256(JCS(entry without hash)), follow
prevHash from the genesis (64 zeros), and confirm the chain reaches every
sealed head.
Unlocking a tier at the resolver
In preparation on epc.is: the resolver and the verifier implement the flow, and it stays off until the credential-type-to-role mapping is configured. The calls look like this.
Ask for a tier on a single-record read:
curl -s -D - -H 'DPP-Tier: Restricted' \
'https://id.epc.is/01/09521002005004?linkType=masterData'
If you do not reach the tier, the resolver answers with two challenges:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="openepcis", error="insufficient_tier", tier="Restricted",
OID4VP request_uri="https://issuer.epc.is/vc/oid4vp/request/3f1c…", session="3f1c…"
Content-Type: application/problem+json
Hand the request_uri to the wallet. A client without a wallet back channel
polls the session at the resolver until status is verified, failed or
expired:
curl -s https://id.epc.is/access/sessions/3f1c…
{ "status": "verified", "receipt": "<jws>" }
Repeat the read with the receipt:
curl -s -H "DPP-Receipt: $RECEIPT" -H 'DPP-Tier: Restricted' \
'https://id.epc.is/01/09521002005004?linkType=masterData'
The receipt is valid for at most 15 minutes and only once per resolver
instance. A receipt bound to another resource answers 403
insufficient_scope; an invalid one answers 401 invalid_token with the reason
in error_description. A receipt grants read access only.
Related pages
- Signed Passports: concepts and availability
- API Reference: the OpenAPI references for the resolver and the EPCIS repository
- Integration Tokens: long-lived tokens for unattended issuance