PingOne Platform APIs

Credential Issuance Rules

Use the Credentials Issuance Rules operations to create, read, and update rules for issuing, updating, and revoking credentials by credential type. Rules are defined for:

  • A specific Credential Type in the endpoint

  • A specific Digital Wallet App in the request body

  • A specific set of users defined by one, and only one, of these filters in the request body:

    • Membership in one or more Groups.

    • Membership in one or more Populations.

    • Satisfying a SCIM query. For information about SCIM syntax and operators, refer to SCIM operators.

A credential rule contains an automation object with available actions as keys: issue, revoke, and update. If an action is set to PERIODIC, the service performs the action at the end of the period. If an action is set to ON_DEMAND, you must use Apply Credential Issuance Rule Staged Changes to perform staged changes for those ON_DEMAND actions.

The general procedure for rules is:

  1. Create: create a new rule to stage actions for for the credential by user

  2. Update: update an existing rule to stage actions for the credential by user

  3. Staged Changes: show actions staged for execution

  4. Apply: act upon credentials staged for actions.

You can also monitor credential rules:

  • All Rules: view all rules defined for a credential type

  • One Rule: view a specific rule for a credential

  • Usage Counts: show counts by action applied to the credential by user

  • Usage Details: show details by action applied to the credential by user

You can, finally, remove a rule for a credential type:

  • Delete: remove a rule from a credential type

For actions set to PERIODIC, an improper credential could cause endless repetitious errors. The service monitors staged changes for errors. When an error occurs during processing, the service adds details of the error to the staged change so that errors can be tracked, counted, and returned to the user. If more than 3 errors occur for the same scheduled staged change, the service unschedules (changes stagedChanges.scheduled from true to false) that staged change so that the service no longer attempts to process it. The user can manually trigger the staged change with Apply Credential Issuance Rule Staged Changes.

Credentials unscheduled due to errors are reported. Some errors are known but there can also be unexpected errors. The errors.errorDetail object provides an error code and message. If the error was related to processing a specific credential field, the field name will be in errors.errorDetail.target. This includes the staged changes that exist when the request is made with 1 or more errors. It does not include a staged change that was failed in the past, but has since completed successfully or was deleted (because the user no longer matches the issuance rule). Requests that report errors include:

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

  • For a credential type with management.mode set to MANAGED, you cannot create an issuance rule for that credential type.

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 Issuance Rules data model

Property Type Required Mutable Description

automation

Object

Required

Mutable

Contains a list of actions, as key names, and the update method for each action.

automation.issue

String

Required

Mutable

The method the service uses to issue credentials with the credential issuance rule. Can be PERIODIC or ON_DEMAND.

automation.revoke

String

Required

Mutable

The method the service uses to revoke credentials with the credential issuance rule. Can be PERIODIC or ON_DEMAND.

automation.update

String

Required

Mutable

The method the service uses to update credentials with the credential issuance rule. Can be PERIODIC or ON_DEMAND.

createdAt

DateTime

N/A

Read-only

Date and time the credential issuance rule was created.

credentialType.id

String

N/A

Read-only

Identifier (UUID) of the credential type with which this credential issuance rule is associated.

digitalWalletApplication.id

String

Optional

Mutable

Identifier (UUID) of the customer’s Digital Wallet App that will interact with the user’s Digital Wallet. Optional, and if present, digital wallet pairing automatically starts when a user matches the credential issuance rule.

environment.id

String

N/A

Read-only

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

filter

Object

Optional

Mutable

Contains one and only one filter (.groupIds, .populationIds, or .scim) that selects the users to which the credential issuance rule applies.

filter.groupIds

String[]

Required/Optional

Mutable

Array of one or more identifiers (UUIDs) of groups, any of which a user must belong for the credential issuance rule to apply. One and only one filter is required in filter, others are optional and cause an error if used.

filter.populationIds

String[]

Required/Optional

Mutable

Array of one or more identifiers (UUIDs) of populations, any of which a user must belong for the credential issuance rule to apply. One and only one filter is required in filter, others are optional and cause an error if used.

filter.scim

String

Required/Optional

Mutable

A SCIM query that selects users to which the credential issuance rule applies. One and only one filter is required in filter, others are optional and cause an error if used. For more information about SCIM syntax and operators, refer to SCIM operators.

id

String

N/A

Read-only

Identifier (UUID) of the credential issuance rule.

notification

Object

Optional

Immutable

Contains notification information. When this property is supplied, the information within is used to create a custom notification.

notification.methods

String[]

Optional

Immutable

Array of methods for notifying the user. Can be EMAIL, SMS, or both.

notification.template

Object

Optional

Immutable

Contains template parameters.

notification.template.locale

String

Optional

Immutable

The ISO 2-character language code used for the notification, for example: en for English.

notification.template.variables

Object[]

Required/Optional

Immutable

An object of name-value pairs that defines the dynamic variables used by the content variant. Required if the template requires variables, otherwise ignored. For more information on dynamic variables, refer to Dynamic variables.

notification.template.variant

String

Optional

Immutable

The unique user-defined name for the content variant that contains the message text used for the notification. For more information on variants, refer to Creating custom contents.

status

String

Required

Mutable

Status of the credential issuance rule. Can be ACTIVE or DISABLED.

updatedAt

DateTime

N/A

Read-only

Date and time the credential issuance rule was last updated. Can be null.

Actions within automation (.issue, .update, and .revoke) can be PERIODIC, the service applies the rule frequently every hour, or ON_DEMAND, the service applies the rule only with an Apply Credential Issuance Rule Staged Changes request. For ON_DEMAND, use Read Credential Issuance Rule Staged Changes to determine staged changes.

The one notification.template object applies a variant and locale to all three credential notification templates: credential_issued, credential_updated, and credential_revoked. When adding a variant or locale to any of the three notification templates, consider adding the same variant or locale to the other notification templates. If a requested variant is not defined, the notification uses the default notification template. If a requested locale is not defined, the notification uses the user’s preferred language or, if the user has no preferred language, the default language of the environment.

Credential Issuance Rules staged changes data model

Property Type Required Mutable Description

stagedChanges.action

String

N/A

Read-only

Action determined by the service that should be taken for the credential based on the request that staged it. Can be ISSUE, UPDATE, or REVOKE.

stagedChanges.createdAt

DateTime

N/A

Read-only

Date and time the change was staged by the service.

stagedChanges.credentialType.id

String

N/A

Read-only

Identifier (UUID) of the credential type with which this credential issuance rule is associated.

stagedChanges.environment.id

String

N/A

Read-only

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

stagedChanges.issuanceRule.id

String

N/A

Read-only

Identifier (UUID) of the credential issuance rule.

stagedChanges.scheduled

String

N/A

Read-only

Whether or not the staged change is scheduled: true if the action on the credential issuance rule is set to PERIODIC and false if the action is set to ON_DEMAND.

stagedChanges.user.id

String

N/A

Read-only

Identifier (UUID) of the user identified by the filter on the credential issuance rule.

stagedChanges.errors

Object[]

N/A

Read-only

Array of objects representing credentials that had errors when attempting an action on it. Refer to Credential Issuance Rules errors object.

Credential Issuance Rules apply staged changes data model

This data model applies only to Read Credential Issuance Rule Staged Changes and Apply Credential Issuance Rule Staged Changes.

Property Type Required Mutable Description

issue

String[]

Optional

Mutable

Array of one or more identifiers (UUIDs) of users whose credentials are in an issue action state and should be issued.

revoke

String[]

Optional

Mutable

Array of one or more identifiers (UUIDs) of users whose credentials are in a revoke action state and should be revoked. Used only in the body of Apply Credential Issuance Rule Staged Changes.

update

String[]

Optional

Mutable

Array of one or more identifiers (UUIDs) of users whose credentials are in an update action state and should be updated. Used only in the body of Apply Credential Issuance Rule Staged Changes.

errors

Object[]

N/A

Read-only

Array of objects representing credentials that had errors when attempting an action on it. Refer to Credential Issuance Rules errors object.

Credential Issuance Rules usage counts data model

Property Type Required Mutable Description

issued

Integer

N/A

Read-only

Count of credentials issued by the rule since the time the credential issuance rule was created.

accepted

Integer

N/A

Read-only

Count of credentials accepted by users of credentials issued by the credential issuance rule since the time the credential issuance rule was created.

updated

Integer

N/A

Read-only

Count of credentials updated by the rule since the time the credential issuance rule was created.

revoked

Integer

N/A

Read-only

Count of credentials revoked by the rule since the time the credential issuance rule was created.

errors

Integer

N/A

Read-only

Count of credentials that caused errors since the time the credential issuance rule was created.

Credential Issuance Rules usage details data model

Property Type Required Mutable Description

issued

Object[]

N/A

Read-only

Credentials issued by the rule since the time the credential issuance rule was created.

issued.user.id

String

N/A

Read-only

Identifier (UUID) of the user identified by the filter on the credential issuance rule.

issued.credential.id

String

N/A

Read-only

Identifier (UUID) of the credential subject to the issue action identified by the credential issuance rule.

issued.createdAt

DateTime

N/A

Read-only

Date and time the credential was issued by the service.

updated

Object[]

N/A

Read-only

Credentials updated by the rule since the time the credential issuance rule was created.

updated.user.id

String

N/A

Read-only

Identifier (UUID) of the user identified by the filter on the credential issuance rule.

updated.credential.id

String

N/A

Read-only

Identifier (UUID) of the credential subject to the update action identified by the credential issuance rule.

updated.createdAt

DateTime

N/A

Read-only

Date and time the credential was updated by the service.

revoked

Object[]

N/A

Read-only

Credentials revoked by the rule since the time the credential issuance rule was created.

revoked.user.id

String

N/A

Read-only

Identifier (UUID) of the user identified by the filter on the credential issuance rule.

revoked.credential.id

String

N/A

Read-only

Identifier (UUID) of the credential subject to the revoke action identified by the credential issuance rule.

revoked.createdAt

DateTime

N/A

Read-only

Date and time the credential was revoked by the service.

errors

Object[]

N/A

Read-only

Array of objects representing credentials that had errors when attempting an action on it. Refer to Credential Issuance Rules errors object.

Credential Issuance Rules errors object

Property Type Required Mutable Description

errors

Object[]

N/A

Read-only

Array of objects representing errors recorded when attempting an action on a credential.

errors.recordedAt

DateTime

N/A

Read-only

Date and time the error was recorded by the service.

errors.errorDetail.code

String

N/A

Read-only

A code that indicates the error encountered by the service. Refer to Credential Issuance Rules staged changes error codes.

errors.errorDetail.target

String

N/A

Read-only

The part of the credential that caused the error encountered by the service.

errors.errorDetail.message

String

N/A

Read-only

A message that describes the error encountered by the service.

credentialType.id

String

N/A

Read-only

Identifier (UUID) of the credential type with which this credential issuance rule is associated.

environment.id

String

N/A

Read-only

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

issuanceRule.id

String

N/A

Read-only

Identifier (UUID) of the credential issuance rule.

user.id

String

N/A

Read-only

Identifier (UUID) of the user identified by the filter on the credential issuance rule.

id

String

N/A

Read-only

Identifier (UUID) of the error.

action

String

N/A

Read-only

Action determined by the service that should be taken for the credential based on the request that staged it. Can be ISSUE, UPDATE, or REVOKE.

scheduled

String

N/A

Read-only

Whether or not the staged change is scheduled: true if the action on the credential issuance rule is set to PERIODIC and false if the action is set to ON_DEMAND.

createdAt

DateTime

N/A

Read-only

Date and time the error was created by the service.

updatedAt

DateTime

N/A

Read-only

Date and time the error was updated by the service.

Credential Issuance Rules staged changes error codes

Error Code Description

TEMPLATE_ERROR

An error in the template placeholders of the cardDesignTemplate SVG.

SVG_ERROR

An error in the syntax of the cardDesignTemplate SVG.

CREDENTIAL_TYPE_INVALID

Credential Type was invalid when the staged change was performed.

FILE_RESOLUTION_ERROR

User attribute for a field with fileSupport did not reference a supported file, such as an unsupported URL, file too large, or error reading file.

CREDENTIAL_TOO_LARGE

Size of data collected for the credential exceeds the maximum that can be stored in a credential.

UNEXPECTED_ERROR

An unexpected error occurred.

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 Issuance Rules errors

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

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

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [filter <message>]

When and details

When: A POST or PUT /issuanceRules request supplies filter as an explicit null, supplies an empty groupIds, populationIds, or scim filter, supplies null entries in a filter array, supplies more than one filter type in filter, or supplies a SCIM filter that cannot be parsed or exceeds 50 components

Details: The Bean-Validation literal for the failing property, for example must not be null for an explicit null filter, groupIds must not be empty for an empty groupIds array, scim must not be empty for an empty SCIM filter, groupIds must not contain null for a null group ID, only 1 filter type may be provided when more than one filter type is supplied, invalid SCIM filter: <parse error> for an unparseable filter, or Search filters cannot include more than 50 components for an overly complex filter (for example Validation Error : [filter only 1 filter type may be provided])

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 /issuanceRules request references a digitalWalletApplication.id that does not exist in the environment, or references a digital wallet application whose PingOne application is not active when the rule is ACTIVE

Details: digitalWalletApplication not found or digitalWalletApplication is not valid for the digitalWalletApplication relationship

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 /issuanceRules request supplies a filter that the directory cannot evaluate, such as a SCIM filter that references an attribute that does not exist

Details: unable to determine matching Users from directory: <directory message>, reported against the filter property

400

INVALID_DATA

REQUIRED_VALUE

Message: The request is missing a required value.

When and details

When: A POST or PUT /issuanceRules request sets status to ACTIVE without providing a filter in filter

Details: a valid filter must be provided to activate this Issuance Rule, reported against the filter property

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 /applyStagedChanges request is made for a rule that is not ACTIVE

Details: issuanceRule is not ACTIVE

400

INVALID_REQUEST

INVALID_VALUE

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

When and details

When: A path identifier cannot be parsed as a UUID, or the request body cannot be deserialized as JSON

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

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST /issuanceRules request creates a rule for a credential type that already has an issuance rule, or for a credential type whose management.mode is MANAGED or that is system-provided

Details: an issuanceRule already exists for the credentialType or credentialType does not allow issuanceRule, respectively

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:issuanceRule permission (POST), the credentialsIssuance:update:issuanceRule permission (PUT or apply), the credentialsIssuance:update:stagedChanges permission (apply staged changes), the credentialsIssuance:delete:issuanceRule permission (DELETE), the credentialsIssuance:read:issuanceRule permission (GET rules, usage counts, and usage details), or the credentialsIssuance:read:stagedChanges permission (GET staged changes)

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, PUT, or DELETE /issuanceRules/{issuanceRuleID} or a staged changes request references an issuance rule that does not exist in 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 processing the request.

Details: None