PingOne Platform APIs

Credential Types

Use the Credentials Types operations to create, read, and update the credential types used by compatible wallet apps.

You must ensure that any fields used in the cardDesignTemplate are defined appropriately in metadata.fields or errors occur when you attempt to create a credential of that type.

Versioning

If the updated credential type differs from the existing credential type, the service saves the existing credential type as a Credential Type Version and increments version.number in the updated credential type. Credential Type Versions can be read with Read All Credential Type Versions.

Automatic deletion and revocation

Typical behavior for credential types is to automatically revoke user credentials when a credential type, user, or environment is deleted. However, some credential types, such as birth certificates, university degrees, or marriage certificates, should never be automatically revoked even if the user or environment is deleted. You control this using onDelete.revokeIssuedCredentials on the credential type.

The selected deletion and revocation behavior cascades over all resources managed by the service: credential types, issuance rules, staged changes, digital wallet applications, digital wallets, and user credentials.

Environment deleted:

  • Delete all credential types

  • Delete all issuance rules

  • Delete all staged changes

  • Delete all digital wallet applications

  • Delete all digital wallets

  • Delete all user credentials

  • Delete all provisioned credentials

  • Delete all credential type counts

  • Delete environment credential count

Population deleted:

  • Remove population from existing issuance rules

Group deleted:

  • Remove group from existing issuance rules

User deleted:

  • Delete user credential

  • Delete digital wallets

Application (associated with digital wallet applications) deleted:

  • No impact

Credential type deleted:

  • Revoke issued credentials based on delete flag

  • Delete issuance rule

Issuance rule deleted

  • Delete staged changes

Digital wallet application deleted:

  • Disable digital wallets that are of this type

Digital wallet deleted:

  • Revoke credentials that were provisioned to the digital wallet based on credential type delete flag

User credential deleted:

  • Revoke provisioned credentials based on credential type delete flag

Regardless of the setting of onDelete.revokeIssuedCredentials, the service always deletes any pending credentials. (Pending credentials are staged for issue but not provisioned to a wallet because no paired digital wallet exists.)

Credential schema

When the service creates a credential from a credential type, it maintains the full credential schema, including attributes without corresponding values in the Create a User Credential request, so that the credential structure is consistent and predictable. It assigns an empty string ("") to any attribute without a value in the request body.

Credential Types data model

Property Type Required? Mutable? Description

cardDesignTemplate

String

Required

Immutable

An SVG formatted image containing placeholders for the credentials fields that need to be displayed in the image. Refer to warning following this table. Not returned with Read All Credential Types. You must Read One Credential Type with the id of the credential type you want to review.

cardType

String

Optional

Mutable

A descriptor of the credential type. Can be non-identity types such as proof of employment or proof of insurance.

createdAt

DateTime

N/A

Read-only

Date and time the credential type was created.

deletedAt

DateTime

N/A

Read-only

Date and time the credential type was deleted. Returned only with Read One Credential Type.

description

String

Optional

Mutable

A description of the credential type.

environment.id

String

N/A

Read-only

PingOne environment identifier (UUID) in which the credential type exists.

expiration

Object

Optional

Mutable

Object that identifies how to evaluate the expiration date. Requires one and only one of after, timestamp, or expression. Permitted only when management.mode is AUTOMATED.

expiration.after

Object

Required/Optional

Mutable

Contains the numeric duration and its time unit for calculating an expiration date.

expiration.after.duration

Integer

Required

Mutable

Length of time before transaction timeout expires; range is from a 1 hour minimum (or equivalent) to an (effectively) unbounded maximum.

expiration.after.timeUnit

String

Required

Mutable

Time unit of transaction timeout; can be SECONDS, MINUTES, HOURS, or DAYS.

expiration.expression

String

Required/Optional

Mutable

PingOne Expression Language (PEL) expression that evaluates to an ISO 8601 date. For more information on PEL, refer to PingOne expression language.

expiration.fieldName

String

Required/Optional

Mutable

On issuance, name of the field in the credential to hold the expiration that, when evaluated, returns an expiration date. Must be unique from all fields defined in the metadata object of Create Credential Type. Required when expiration.type is SOFT. Optional when expiration.type is HARD and ignored if used.

expiration.timestamp

DateTime

Required/Optional

Mutable

The date and time to expire in ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ format (milliseconds optional).

expiration.type

String

Required

Mutable

Indicates how expiration of the credential is presented. Can be SOFT or HARD. A SOFT expiration appears as a user-defined field (named in fieldName) in the credential but returns no expiration date in Read One User Credential. A HARD expiration appears as a standards-based expiration field in the credential and returns an expiration date in Read One User Credential.

id

String

N/A

Read-only

Identifier (UUID) associated with the credential type.

issuer.id

String

N/A

Read-only

The identifier (UUID) of the issuer.

issuerName

String

Optional

Mutable

Issuer name associated with the card, can differ from title.

management.mode

String

Optional

Mutable

Management mode of the credential type. Can be AUTOMATED (the default) or MANAGED. Refer to the note following this table.

metadata

Object

Required

Mutable

Contains the names, data types, and other metadata related to the credential; refer to metadata object data model.

multiple

Object

Optional

Mutable

Object containing directives that enable you to Issue multiple credentials to a user based on a directory attribute.

multiple.expression

String

Required

Mutable

A PingOne Expression Language (PEL) expression that evaluates to a number or array. If an array, calculates the array length for the count. Populates the limit to a variable, ITERATOR, available to PEL expressions in metadata.fields.attribute.

onDelete.revokeIssuedCredentials

Boolean

Optional

Mutable

Whether user credentials are automatically revoked when a credential type, user, or environment is deleted. Defaults to true. For credential types (such as birth certificates, university degrees, or marriage certificates) that should never be automatically revoked even if the user or environment is deleted, set this to false.

title

String

Required

Immutable

Title of the credential. Verification sites are expected to be able to request the issued credential from the compatible wallet app using the title.

updatedAt

DateTime

N/A

Read-only

Date and time the credential type was last updated; can be null.

version.id

String

N/A

Read-only

Identifier (UUID) of this version of the credential type. The service assigns identifiers.

version.number

Integer

N/A

Read-only

Version of this credential type. The service assigns versions.

version.uri

String

N/A

Read-only

A URI to of this version of the credential type. The service assigns URIs.

The design template, the SVG in cardDesignTemplate, can be modified using the API. However, if subsequently opened in the admin console, the admin console reverts the credential type to the default design template. As long as the credential type is not modified via the admin console, the customized design template remains in place, but displays incorrectly in the admin console. If a minor change is made in the admin console, such as simply changing a description in the credential, the customized design template is overwritten.

Multiple credential issuance is limited to 10 credentials issued for one user for one credential type. You must ensure that the content of the directory attribute will not exceed the 10 credential limit when using your PEL expressions in multiple.expression and metadata.fields.attribute.

If management.mode is AUTOMATED, the credential type is only issued by its associated credential issuance rule. If management.mode is MANAGED, the credential type is only issued by Create a User Credential or Update a User Credential API requests. If you change management.mode from AUTOMATED to MANAGED and an associated issuance rule exists, the rule is disabled, but not deleted.

If management.mode is AUTOMATED, you can value one and only one of the three properties in the expiration object and the associated credential issuance rule automatically assigns an expiration date when it issues the credential. If management.mode is MANAGED and an expiration object is present, it causes an error.

If you want to change management.mode from AUTOMATED to MANAGED, but one of the three properties in the expiration object is valued, you must remove the expiration object. Use Update the Credential Type with no expiration object, which removes it from the credential type, and with management.mode set to MANAGED.

For a credential type, if management.mode is AUTOMATED and no credential issuance rule exists for that credential type, no error occurs. That credential type is simply never issued.

metadata object data model

The metadata object is not returned with Read All Credential Types. You must Read One Credential Type with the id of the credential type you want to review.

Property Type Required? Mutable? Description

backgroundImage

String

Optional

Mutable

URL to an image of the background to show in the credential. Must be no more than 50 KB in size.

bgOpacityPercent

String

Optional

Mutable

Percent opacity of the background image in the credential. High percentage opacity may make reading text difficult.

cardColor

String

Optional

Mutable

Color to show on the credential.

columns

Integer

Optional

Mutable

Number of columns of visible fields to use when displaying the credential. Must be between 1 and 3. Defaults to 1.

description

String

Optional

Mutable

Description of the credential.

fields

Object[]

Optional

Mutable

Array of objects representing the fields.

fields.attribute

String

Required/Optional

Mutable

Name of the PingOne Directory attribute. Required if field.type is Directory Attribute, otherwise optional and ignored if used. Refer to fields.attribute definition.

fields.default

String

Optional

Mutable

Assigns a default value if a PingOne Expression Language (PEL) in the fields.attribute evaluates to no value.

fields.id

String

Required

Mutable

Identifier of the field. Ping Identity recommends that id is text formatted as "<fields.type> → <fields.title>" to show the type of data expected as well as for what it is used. Examples include: "Alphanumeric Text → Department" or "Directory Attribute → Username".

fields.fileSupport

String

Optional

Mutable

Specifies how an image is stored in the credential; refer to fields.fileSupport types.

fields.isVisible

Boolean

Required

Mutable

Whether the field should be visible to viewers of the credential.

fields.required

Boolean

Optional

Mutable

Whether the field is required for the credential. Defaults to false.

fields.title

String

Required

Mutable

Descriptive text when showing the field.

fields.type

String

Required

Mutable

Type of data in the field; refer to fields.type types.

fields.value

String

Required/Optional

Mutable

The text to appear on the credential for a type of Alphanumeric Text. Required if type is Alphanumeric Text and management.mode is AUTOMATED, optional if type is Alphanumeric Text and management.mode is MANAGED (effectively a default that can be overridden by a data value in Create a User Credential or Update a User Credential), and otherwise ignored if present.

logoImage

String

Optional

Mutable

URL to an image of the logo to show in the credential. Must be no more than 25 KB in size.

name

String

Optional

Mutable

Name of the credential.

textColor

String

Optional

Mutable

Color of the text to show on the credential.

version

Integer

Optional

Mutable

Version of this credential metadata. If not provided, the service assigns a version.

In a credential, the information is stored as name-value pairs where fields defines those name-value pairs. Effectively, fields.title is the key and its value is: fields.value, extracted from the PingOne Directory attribute named in fields.attribute, or returned by the PEL expression in fields.attribute.

fields.attribute definition

Although fields.attribute is always a string type, the service supports two interpretations of its string.

If the string begins with ${ and ends with }, the string is interpreted as a PingOne Expression Language (PEL) expression. As a PEL expression, the string must have user. before any attribute names. A PEL expression is essential to xref:[Issue multiple credentials to a user based on a directory attribute]. The PEL expression extracts specific elements from the multiple potential credentials found in the attribute.

If the string does not have ${ and }, the string is interpreted as the traditional pointer to an attribute name in the directory. That is, you supply an attribute name as the string and the service supplies the value of that attribute to the credential. When used as a pointer, the string does not need user. to reference an attribute.

fields.fileSupport types

A credential field that uses a type of Directory Attribute can contain a URL that references a JPEG, PNG, or GIF image file uploaded with Create Image. The credential type is limited to 5 fields that have fileSupport set to BASE64_STRING or INCLUDE_FILE. For credentials, an image file has a maximum size of 2 MB. A credential cannot exceed 2.5 MB including all images.

If an image field is in the credential type, before issuing a credential you must:

  1. If a suitable standard attribute is unavailable, use Create Attribute to create a custom directory attribute in the user schema that can be referenced by the credential field.

  2. Use Create Image to make the image available to the service.

  3. Use Update User to place the URL returned by Create Image in the attribute in the user schema.
Type Description

BASE64_STRING

Image is base64-encoded to a string in the credential.

INCLUDE_FILE

Image binary is included in the credential.

REFERENCE_FILE

Only a URL referencing the image is in the credential. The image binary remains stored external to the credential.

fields.type types

Type Description

Alphanumeric Text

A static text string of letters, numbers, or punctuation set on fields.value.

Issued Timestamp

Date and time the credential was issued.

Directory Attribute

Any PingOne Directory standard or custom attribute. When used in a credential for a user, the service reads that attribute from the user and puts the value in the credential. The name of the attribute is in fields.attribute.

Automatic deletion and revocation

Typical behavior for credential types is to automatically revoke user credentials when a credential type, user, or environment is deleted. However, some credential types, such as birth certificates, university degrees, or marriage certificates, should never be automatically revoked even if the user or environment is deleted. You control this using onDelete.revokeIssuedCredentials on the credential type.

The selected deletion and revocation behavior cascades over all resources managed by the service: credential types, issuance rules, staged changes, digital wallet applications, digital wallets, and user credentials.

If onDelete.revokeIssuedCredentials is true:

  • User credentials are revoked and deleted when the credential type is deleted.

  • Provisioned credentials are revoked when a user credential is deleted, its credential type is deleted, or its digital wallet is disabled or deleted.

If onDelete.revokeIssuedCredentials is false:

  • User credentials are only revoked if the issuance rule causes it to be revoked or if Update a User Credential sets the expiration date.

  • Provisioned credentials are revoked if the user credential is revoked (refer to previous item).

Issue multiple credentials to a user based on a directory attribute

Some customers must issue multiple credentials to a user based on a directory attribute. For example, a bank might issue credit cards in their own name while also issuing credit cards branded for their customers. A user may have more than one of these credit cards in their wallet. The directory service requires an attribute that contains all the credit cards for that user and the service must support credential issuance to any or all of that user’s credit cards.

The customer can define a single directory attribute for each user to hold a data object that contains the different accounts owned by the user. Our hypothetical bank wants to support the end user being able to present a verifiable credential that contains only the information from one of these accounts. Although issuance of multiple credentials is initiated by a single directory attribute, definition of the credential type can reference any directory attributes for its fields.

The definition of the data object is up to the customer. They then use PingOne Expression Language (PEL) expressions to retrieve any information as required. The Credential Types multiple.expression contains a PEL expression that counts qualifying entries in the data object. The Credential Types metadata.fields.attribute contains a PEL expression to retrieve individual data elements that populates a field in the credit type definition.

When you Apply Credential Issuance Rule Staged Changes for a user for a credential type that has multiple configured, the service creates multiple, separate user credentials for the credential type.

An example may better illustrate applying these concepts.

Example data object

Our hypothetical bank customer, BigBank, uses this JSON object, stored as a JSON binary large object (blob), as the source for credit card information.

{
  "credit_cards": {
    "branded": [
      {
        "oem_merchant": "ChainRetailer",
        "customer_id": "0010380",
        "user_id": "1506980157738"
      },
      {
        "oem_merchant": "GlobalOil",
        "customer_id": "0475932",
        "user_id": "1506980157739"
      }
    ],
    "owned": [
      {
        "customer_id": "0010380",
        "int_id" : "03918203198"
      },
      {
        "customer_id": "0475932",
        "int_id" : "03918203100"
      }
    ]
  }
}

An administrator at BigBank creates two different credential types, one each for branded and owned. Each credential type is configured to issue a credential for each JSON object in that array.

Example API

This demonstrates the API using the branded array. An administrator at BigBank created this credential type for branded.

A body for Create a credential type (automated) that creates multiple credentials from the data object for the credit_cards.branded is:

{
    "title": "Branded Cards",
    "description": "Example for branded cards attribute for BigBank",
    "metadata": {
        "fields": [
            {
                "id": "title",
                "title": "oem_merchant",
                "attribute": "${user.credit_cards['branded'][__ITERATOR__].oem_merchant}",
                "isVisible": true,
                "type": "Directory Attribute",
                "default": "Use this if missing"
            },
            {
                "id": "Directory Attribute -> user_id",
                "title": "user_id",
                "attribute": "${user.credit_cards['branded'][__ITERATOR__].user_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            },
            {
                "id": "Directory Attribute -> customer_id",
                "title": "customer_id",
                "attribute": "${user.credit_cards['branded'][__ITERATOR__].customer_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            }
        ]
    },
    "cardDesignTemplate": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 740 480\">...</svg>",
    "multiple": {
        "expression": "${user.credit_cards['branded']}"
    }
}

The PEL expression in multiple.expression returns the count of objects in the credit_cards.branded object array of the data object. This populates the iteration limit of the system ITERATOR variable seen in the PEL expressions of the three metadata.fields.attribute values.

A body for Create a credential type (automated) that creates multiple credentials from the data object for the credit_cards.owned is:

{
    "title": "Owned",
    "description": "Example for owned attribute for BigBank",
    "metadata": {
        "fields": [
            {
                "id": "Directory Attribute -> int_id",
                "title": "int_id",
                "attribute": "${user.credit_cards['owned'][__ITERATOR__].int_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            },
            {
                "id": "Directory Attribute -> customer_id",
                "title": "customer_id",
                "attribute": "${user.credit_cards['owned'][__ITERATOR__].customer_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            }
        ],
        "textColor": "#000000",
        "version": 4
    },
    "cardDesignTemplate": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 740 480\">...</svg>",
    "multiple": {
        "expression": "${user.credit_cards['owned']}"
    }
}

The PEL expression in multiple.expression returns the count of objects in the credit_cards.owned object array of the data object. This populates the iteration limit of the system ITERATOR variable seen in the PEL expressions of the two metadata.fields.attribute values.

Important considerations

  1. Do not use a multi-valued attribute type. Use a single JSON attribute that contains the necessary arrays.

    When configuring a custom JSON attribute for issuing multiple credentials for a user, the administrator can set it to a multi-valued type, which allows the attribute to be an array of JSON blobs. The PingOne Directory does not guarantee ordering for multi-valued attributes. Multi-valued attributes values are treated as a set rather than a list. This conflicts with how the service determines if a credential has changed, where order is essential. For example, a user has three credentials issued using a multi-valued type of [A, B, C]. If you add another JSON blob to the user attribute, one might expect the change to look like [A, B, C, D] (where each letter is a different credential) and issue one more credential to the user. However, with a multi-valued custom JSON attribute, the change may look like [A, C, D, B]. When the service compares the order, it interprets that two credentials have been updated and one more credential has been added.

    Due to this involuntary re-ordering behavior, multi-valued custom JSON attributes are strongly discouraged.

  2. Revocation can be affected by re-ordering.

    If the user has an array like [A, B, C] so that the service issues three credentials and an administrator then revokes the credential B, credential B remains revoked. If the user is updated to change some values in A, B, and C, A and C update while B remains revoked. However, if the user is updated with a new object or value added to the array such that it becomes [A, D, B, C], credential C updates to the values of B and a new credential issues for C. No credential will be issued or updated to have the values of D because it is in the second place and the credential for second place was revoked.

    To mitigate this behavior, always add new entries to the end of the arrays in the JSON blob.

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.