PingOne Platform APIs

Credential Issuers

Use the Credential Issuers operations to retrieve or update the credential issuer information. A default credential issuer profile, which enables issuance of credentials, is automatically created when the credential service is added to an environment.

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 Issuers data model

Property Type Required Mutable Description

applicationInstance.id

String

N/A

Read-only

Identifier (UUID) of the application instance registered with the PingOne platform service. This enables the client to send messages to the service.

credentialSigning

Object

Optional

Mutable

Object with the configuration for sending verifiable credentials (VC-JWT or SD-JWT) to the customer’s remote signing service at credentialSigning.url for signing with their private key.

credentialSigning.url

String

Required

Mutable

URL to which to send verifiable credentials (VC-JWT or SD-JWT) for signing with their private key. Must be a valid URL with a protocol of HTTPS.

credentialSigning.headers

Object

Optional

Mutable

Object of headers as key-value pairs, where the key is the name of a header field and the value is the value of the header field, to send with the verifiable credentials (VC-JWT or SD-JWT) for signing.

credentialSigning.headers.<field>

String

Required

Mutable

The placeholder, <field>, is the name of the header field to add to the request. The value assigned to this becomes the value of the header field created.

createdAt

DateTime

N/A

Read-only

Date and time the issuer profile was created.

did.method

String

Optional

Mutable

Decentralized Identifier (DID) method for the issuer. Can be WEB or WEBVH. Initially set to WEB. Refer to DID WEBVH (did:webvh).

did.value

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

did.web.host

String

N/A

Read-only

The hosting provider. Always "PING"

did.web.useCustomDomain

Boolean

Optional

Mutable

Whether or not the credential issuer uses its custom domain in its DID when the issuer has Custom Domains enabled. Defaults to true and uses the custom domain, whereas false uses auth.pingone.com

id

String

N/A

Read-only

Identifier (UUID) of the credential issuer.

logo

String

Optional

Mutable

A URI containing the logo for the issuer. Restricted to a valid URL with a scheme of https: or a scheme of data: with a base64-encoded image. Included in credentials issued.

name

String

Required

Immutable

The name of the credential issuer. Included in credentials issued.

siteUrl

String

Optional

Mutable

URL, chosen by the issuer, that references the issuer in issued credentials.

updatedAt

DateTime

N/A

Read-only

Date and time the credential issuer profile was last updated. Can be null.

In the credentialSigning object, the credentialSigning.headers object defines headers to add to the signing request sent to the customer’s credentialSigning.url. For example:

    "headers": {
        "ClientID": "016e1474-7c62-b944-0a96-b467731ef0bd"
    }

Creates a header on the signing request such as:

ClientID: 016e1474-7c62-b944-0a96-b467731ef0bd

The logo and name can be shown to the user when indicating the credential issuer by the wallet app using using the PingOne Neo Native SDKs with getIssuerMetadata for Android and getCredentialIssuerMetadataFromClaim(_:) for iOS.

DID WEBVH (did:webvh)

The WEBVH DID method, where VH stands for Verifiable History, extends did:web. It maintains simple domain-to-DID resolution (via HTTPS) of did:web while adding a cryptographically verifiable history to the DID without blockchains or ledgers. The Verifiable History records all changes (DID Document versions) in a JSON Lines log (did.jsonl), chained via hashes and signed proofs, allowing anyone to verify the full lifecycle from creation to deactivation. A unique, history-bound identifier, called a Self-Certifying Identifier (SCID), derived from the first DID log entry ensures tamper-resistance and enables portability. The SCID appears between did:webvh and the domain in the DID identifier. For example:

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

    • did:webvh:

    • SCID of the did:webvh

    • auth.pingone.com:

    • UUID of the issuer’s environment

    • #

    • UUID of the signing key

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

    • did:webvh:

    • SCID of the did:webvh

    • :

    • issuer’s custom domain

    • #

    • UUID of the signing key

The shortcoming of did:webvh is that it is not as widely accepted by verifiers as did:web.

Response codes

Code Message

200

Successful operation.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

500

Unexpected server error.

Credential Issuers errors

In addition to the general error codes, credential issuer operations can return the following errors:

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

400

INVALID_DATA

INVALID_VALUE or OUT_OF_RANGE

Message: Validation Error : [<property> <message>]

When and details

When: A POST or PUT /credentialIssuerProfile request supplies a name that is blank, has invalid characters, or is longer than 256 characters, a logo that is empty, is not a valid HTTPS or data: URL, is not a base64-encoded image, does not use a valid image media type, or does not decode as base64, or a siteUrl that is empty, does not use the HTTPS protocol, or is not a valid URL

Details: The Bean-Validation literal for the failing property, for example must not be empty or blank for a blank name, size must be between 1 and 256 with rangeMinimumValue and rangeMaximumValue inner errors and the OUT_OF_RANGE detail code for a name longer than 256 characters, must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens for a name with invalid characters, must be a base64 encoded image for a logo without ;base64,, or url must be https for a non-HTTPS siteUrl (for example Validation Error : [siteUrl url must be https])

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [did.method must not be null]

When and details

When: A PUT /credentialIssuerProfile request omits did.method

Details: must not be null, for example Validation Error : [did.method must not be null]

400

INVALID_DATA

UNIQUENESS_VIOLATION

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

When and details

When: A POST /credentialIssuerProfile request attempts to create a credential issuer profile when one already exists in the environment

Details: A resource with the specified name already exists.

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A POST or PUT /credentialIssuerProfile request sets did.method to WEBVH when the did:webvh feature flag is off for the environment

Details: did:webvh not supported in this environment

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: The request body cannot be deserialized as JSON, such as a JSON syntax error or a property with the wrong JSON type

Details: For a JSON field conversion error, the target is the field path and the detail message is Invalid value for attribute.. Otherwise no detail is returned

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the credentialsIssuance:create:issuerProfile permission (POST), the credentialsIssuance:update:issuerProfile permission (PUT), or the credentialsIssuance:read:issuerProfile permission (GET)

Details: None

404

NOT_FOUND

None

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

When and details

When: A GET or PUT /credentialIssuerProfile request references an environment that has no credential issuer profile (the profile was not automatically created when the credential service was added to the environment)

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 creating, reading, or updating the credential issuer profile, such as a DID log generation failure.

Details: None