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:

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.

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 Filtering collections.

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.

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.