API docs by Redocly

UNTP Identity Resolver API (0.8.0)

Download OpenAPI specification:

Implementation guidance for the UNTP Identity Resolver (IDR) specification. This API implements the Discover-Resolve-Verify workflow defined by the UNTP IDR specification, enabling supply chain actors to resolve product and facility identifiers from any registered identifier scheme to linked digital credentials such as Digital Product Passports (DPPs), Digital Conformity Credentials (DCCs), Digital Facility Records (DFRs), and Digital Traceability Events (DTEs).

UNTP does not mandate GS1. Identifier key types, path shape, and optional multi-segment ("qualifier") paths are defined per scheme. GS1 Digital Link is one supported encoding; ISO/IEC 15459 with ASC MH10 Data Identifiers, opaque registry IDs, Identification Links, and other EN 18219-aligned families are equally valid when registered as namespaces.

Standards Compliance

  • ISO/IEC 18975 — Encoding and resolving identifiers over HTTP
  • IETF RFC 9264 — Linkset media type for typed link collections
  • W3C DID Resolution — Decentralised identifier resolution patterns
  • IETF RFC 8615 — Well-known URI discovery mechanism

Functional Layers

The API is organized into three functional layers:

  1. Resolution (public) — Anonymous, unauthenticated resolution of identifiers to linksets or redirects. This is the core conformity surface that supply chain verifiers interact with.
  2. Link Registration (management) — Authenticated API for registering and managing link resolver entries that associate identifiers with typed link targets.
  3. Identifier Scheme Management — Authenticated API for configuring permitted identifier schemes (namespaces and application identifiers) before link registration can occur.

Normative Requirements

This API addresses UNTP IDR normative requirements IDR-01 through IDR-14. Key requirements include: IDR-01 (identifier scheme registration), IDR-02 (link registration), IDR-06/07/08 (resolution with link type, language, and context negotiation), IDR-09 (optional scheme-defined path grouping), IDR-10 (secure targets with encryption and access roles), and IDR-14 (resolver description discovery).

Identifiers

Manage permitted identifier schemes (namespaces and their application identifiers). An identifier scheme must be registered before any link registration can reference it. Each scheme defines a namespace, a set of application identifiers (primary keys, qualifiers, data attributes) with regex validation patterns, and their relationships. Implements IDR-01 (scheme registration), IDR-03 (identifier validation), and IDR-04 (scheme configuration).

Create or update identifier

Registers or updates an identifier scheme configuration. Defines the namespace, application identifiers (primary keys, qualifiers, data attributes), their regex validation patterns, and relationships. An identifier scheme MUST be registered before any link registration can occur for that namespace. If the namespace already exists, the configuration is replaced (upsert semantics).

Authorizations:
bearer
Request Body schema: application/json
required
namespace
required
string

Unique name for the identifier scheme (e.g. "gs1", "nlis", "integrity-systems"). Must match the scheme's registration in the UNTP IDR register. This value appears as the first path segment in resolution URLs.

namespaceURI
string

Optional URI providing an authoritative reference for the identifier scheme (e.g. the scheme owner's domain or specification URL). Informational — used for documentation and provenance, not for resolution.

namespaceProfile
string

Optional profile identifier for scheme-specific resolver configuration. Allows a single namespace to support multiple resolution profiles (e.g. different validation rules or link type vocabularies for different use cases).

required
Array of objects (ApplicationIdentifier) non-empty

The set of identifier types supported within this scheme. Must include at least one primary identifier (type "I"). Optional type "Q" path continuations and type "D" data attributes are scheme-specific and not required.

Responses

Request samples

Content type
application/json
{
  • "namespace": "products.sample-register.example",
  • "namespaceURI": "",
  • "namespaceProfile": "",
  • "applicationIdentifiers": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Application identifier upserted successfully"
}

Delete identifier by namespace

Permanently removes an identifier scheme and all its application identifier configurations. Existing link resolver entries that reference this namespace will no longer resolve.

Authorizations:
bearer
query Parameters
namespace
required
string
Example: namespace=example-identifier-scheme

The namespace of the identifier scheme to delete (e.g. "gs1", "nlis"). Must match an existing registered scheme.

Responses

Response samples

Content type
application/json
{
  • "message": "Application identifier deleted successfully"
}

Get identifier by namespace

Retrieves the configuration for one or all registered identifier schemes. When a namespace is specified, returns that scheme's configuration. When omitted, returns all registered schemes. Useful for inspecting which identifier types and validation patterns are currently configured.

Authorizations:
bearer
query Parameters
namespace
string
Example: namespace=example-identifier-scheme

The namespace of the identifier scheme to retrieve (e.g. "gs1", "nlis"). If not provided, all registered identifier schemes are returned.

Responses

Response samples

Content type
application/json
Example
{
  • "namespace": "example-identifier-scheme",
  • "applicationIdentifiers": [
    ]
}

Health check

Responses

Response samples

Content type
application/json
{
  • "status": "OK"
}