--- title: Credential Issuance Rules description: 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: component: pingone-api page_id: pingone-api:credentials:credential-issuance-rules canonical_url: https://developer.pingidentity.com/pingone-api/credentials/credential-issuance-rules.html section_ids: assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service credential-issuance-rules-data-model: Credential Issuance Rules data model credential-issuance-rules-staged-changes-data-model: Credential Issuance Rules staged changes data model credential-issuance-rules-apply-staged-changes-data-model: Credential Issuance Rules apply staged changes data model credential-issuance-rules-usage-counts-data-model: Credential Issuance Rules usage counts data model credential-issuance-rules-usage-details-data-model: Credential Issuance Rules usage details data model credential-issuance-rules-errors-object: Credential Issuance Rules errors object credential-issuance-rules-staged-changes-error-codes: Credential Issuance Rules staged changes error codes response-codes: Response codes --- # 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](credential-types.html) in the endpoint * A specific [Digital Wallet App](digital-wallet-apps.html) 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](../platform/groups.html). * Membership in one or more [Populations](../platform/populations.html). * Satisfying a SCIM query. For information about SCIM syntax and operators, refer to [SCIM operators](../platform/users/users-1.html#users-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](credential-issuance-rules/apply-credential-issuance-rule.html) to perform staged changes for those `ON_DEMAND` actions. The general procedure for rules is: 1. [Create](credential-issuance-rules/create-credential-issuance-rule.html) - create a new rule to stage actions for for the credential by user 2. [Update](credential-issuance-rules/update-credential-issuance-rule.html) - update an existing rule to stage actions for the credential by user 3. [Staged Changes](credential-issuance-rules/read-all-credential-issuance-rule-staged-changes.html) - show actions staged for execution 4. [Apply](credential-issuance-rules/apply-credential-issuance-rule.html) - act upon credentials staged for actions. You can also monitor credential rules: * [All Rules](credential-issuance-rules/read-all-credential-issuance-rules.html) - view all rules defined for a credential type * [One Rule](credential-issuance-rules/read-one-credential-issuance-rule.html) - view a specific rule for a credential * [Usage Counts](credential-issuance-rules/read-credential-issuance-rule-usage-counts.html) - show counts by action applied to the credential by user * [Usage Details](credential-issuance-rules/read-credential-issuance-rule-usage-details.html) - show details by action applied to the credential by user You can, finally, remove a rule for a credential type: * [Delete](credential-issuance-rules/delete-credential-issuance-rule.html) - 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](credential-issuance-rules/apply-credential-issuance-rule.html). 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](#credential-issuance-rules-staged-changes-error-codes). 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: * [Read Credential Issuance Rule Staged Changes](credential-issuance-rules/read-all-credential-issuance-rule-staged-changes.html) * [Read Credential Issuance Rule Usage Counts](credential-issuance-rules/read-credential-issuance-rule-usage-counts.html) * [Read Credential Issuance Rule Usage Details](credential-issuance-rules/read-credential-issuance-rule-usage-details.html) * [Apply Credential Issuance Rule Staged Changes](credential-issuance-rules/apply-credential-issuance-rule.html) | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | - For a [credential type](credential-types.html) 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](credential-types.html) 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](../platform/reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](../platform/reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](../platform/roles/predefined-roles.html#automatic-role-assignment). * [Group Role Assignments](../platform/group-role-assignments/group-role-assignments.html). * [User Role Assignments](../platform/users/user-role-assignments.html). Refer to [Roles Management](../platform/roles.html) 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](digital-wallet-apps.html) that will interact with the user's [Digital Wallet](digital-wallets.html). 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](../platform/users/users-1.html#users-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`. | | `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](../platform/notifications/notifications-templates.html#notifications-templates-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](../platform/notifications/notifications-templates.html#notifications-templates-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](credential-issuance-rules/apply-credential-issuance-rule.html) request. For `ON_DEMAND`, use [Read Credential Issuance Rule Staged Changes](credential-issuance-rules/read-all-credential-issuance-rule-staged-changes.html) 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-errors-object). | ## Credential Issuance Rules apply staged changes data model This data model applies only to [Read Credential Issuance Rule Staged Changes](credential-issuance-rules/read-all-credential-issuance-rule-staged-changes.html) and [Apply Credential Issuance Rule Staged Changes](credential-issuance-rules/apply-credential-issuance-rule.html). | 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](credential-issuance-rules/apply-credential-issuance-rule.html). | | `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](credential-issuance-rules/apply-credential-issuance-rule.html). | | `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). | ## 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). | ## 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](#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. |