PingOne Platform APIs

Credential Verifier Decentralized Identifiers

W3C defines Decentralized IDs (DIDs) as a means to identify an entity in a decentralized ecosystem. See the W3C DIDs spec for details. An entities DID is represented as a string and used in the different ID fields, such as issuer, subject, audience, or holder, for Java Web Tokens (JWTs), Verifiable Credentials (VCs), and other JSON objects. The DID is used to find public keys for the entity as well as optional information about how to interact with the entity.

The DID specification supports multiple ways to store and represent the DID. Every DID is a colon-separated string with the literal did, a method name, and method-specific data. W3C maintains a list of all of the current DID methods.

A did:web identifier is used in the signed JWT that is returned by Credentials Verifications when the wallet requests the Authorization Request. The wallet then resolves the did:web to get the public keys and verify the JSON Web Token (JWT) signature. This supports environments with and without custom domains.

Unlike in Credentials Issuance, a different DID identifier is used for every presentation session because the JSON Web Key Set (JWKS) used is different for each session.

PingOne Credentials uses did:web for the issuer and verifier and did:ion for the holder or subject. PingOne also supports did:ion for all parties for backwards compatibility.

PingOne hosted verifier did:web

The service supports retrieving the did:web documents of verifiers hosted by PingOne on both the standard auth.pingone.com domain (and regional variants by top level domain, TLD) and custom domains. The DID document contains the public keys for the verifier and optional information about how to interact with the verifier. To retrieve the DID document:

  1. The DID of a verifier hosted on the standard auth.pingone.com domain is in the format:

    • did:web:

    • auth.pingone.com:

    • UUID of the verifier’s environment

    • :verifier:

    • UUID of the presentation session

    • #

    • UUID of the signing key

      For an environment UUID 8fd6a2f0-c568-4de8-a319-eb8ddff49dff and presentation session UUID d08008f2-d9dc-4d93-8eeb-9d2f7f50b620, the corresponding URL to retrieve the DID document is:

      https://auth.pingone.com/8fd6a2f0-c568-4de8-a319-eb8ddff49dff/verifier/d08008f2-d9dc-4d93-8eeb-9d2f7f50b620/did.json

  2. The DID of a verifier hosted on a custom domain is in the format:

    • did:web:

    • the verifier’s custom domain

    • :verifier:

    • UUID of the presentation session

    • #

    • UUID of the signing key

      For a custom domain verifier.customerdomain.com and presentation session UUID d08008f2-d9dc-4d93-8eeb-9d2f7f50b620, the corresponding URL to retrieve the DID document is:

      https://verifier.customerdomain.com/d08008f2-d9dc-4d93-8eeb-9d2f7f50b620/did.json

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Credential verifier DID data models

Property Type Required Mutable Description

@context

String

N/A

Read-only

URL to the DID scheme

id

String

N/A

Read-only

A unique identifier that conforms to DID Syntax

verificationMethod.id

String

N/A

Read-only

A unique identifier that conforms to DID URL Syntax

verificationMethod.controller

String

N/A

Read-only

The entity that controls the DID in DID Syntax. In PingOne Credentials, the method-specific data is always equal to the domain part of the request URL

verificationMethod.type

String

N/A

Read-only

Name for the type of JWK represented

verificationMethod.publicKeyJwk

String

N/A

Read-only

A JSON Web Key that conforms to RFC 7517, JSON Web Key (JWK). The contents vary by algorithm as discussed in RFC 7518, JSON Web Algorithms (JWA).

authentication

String

N/A

Read-only

A unique identifier that conforms to DID Syntax including in its fragment a UUID for the key of the verificationMethod.publicKeyJwk

assertionMethod

String

N/A

Read-only

A unique identifier that conforms to DID Syntax including in its fragment a UUID for the key of the verificationMethod.publicKeyJwk

Credential Verifier DID errors

In addition to the general error codes, credential verifier DID document requests can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_REQUEST

None

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A path identifier cannot be parsed as a UUID

Details: None. The top‑level code is INVALID_REQUEST even though the message text is the INVALID_DATA default message.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: The DID document request references a presentation session that is no longer in the session store, the session belongs to a different environment than the one in the request URL, or the session’s protocol is not OPENID4VP

Details: None

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: The service encounters an internal error while building the DID document.

Details: None