--- title: User Credentials description: Use the User Credentials service to create a user credential and get the credential status. To issue the credential to the user you must first create a credential type (automated) or create a credential type (managed). After you create a credential type, you can issue credentials to users two ways depending on the management.mode of the credential type: component: pingone-api page_id: pingone-api:credentials:user-credentials canonical_url: https://developer.pingidentity.com/pingone-api/credentials/user-credentials.html section_ids: assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service user-credentials-data-model: User Credentials data model credentialing-data-object-data-model: data object data model provisioned-credentials-data-model-credential: Provisioned Credentials data model (credential) response-codes: Response codes --- # User Credentials Use the User Credentials service to create a user credential and get the credential status. To issue the credential to the user you must first [create a credential type (automated)](credential-types/create-credential-type-automated.html) or [create a credential type (managed)](credential-types/create-credential-type-managed.html). After you create a credential type, you can issue credentials to users two ways depending on the `management.mode` of the credential type: * If `management.mode` is `AUTOMATIC`, you [create a credential issuance rule](credential-issuance-rules/create-credential-issuance-rule.html) and the service issues the credential to all users who match the rule. * if `management.mode` is `MANAGED`, you [create a user credential](#user-credentials/create-a-user-credential) or [update a user credential](#user-credentials/update-a-user-credential) and the service issues the credential to that user. Regardless of `management.mode`, you can [revoke a user credential](user-credentials/revoke-a-user-credential.html), [read all user credentials](user-credentials/read-all-user-credentials.html), [read one user credential](user-credentials/read-one-user-credential.html), or [read one user credential wallets](user-credentials/read-one-user-credential-wallets.html). ## 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. ## User Credentials data model | Property | Type | Required? | Mutable? | Description | | ----------------------------------------- | --------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createdAt` | DateTime | N/A | Read-only | Date and time the user credential was created. | | `credentialType.id` | String | Required | Immutable | Identifier of the credential type. | | `data` | Object | Optional | Mutable | Fields submitted for the credential. | | `data.` | String | Required/Optional | Mutable | Fields for user data; refer to [data object data model](#credentialing-data-object-data-model). | | `environment.id` | String | N/A | Read-only | Identifier (UUID) of the environment associated with the user. | | `expiresAt` | DateTime | Optional | Mutable | The date that the user credential expires. If this value is null, the credential never expires. | | `id` | String | N/A | Read-only | Identifier (UUID) of the user credential. | | `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.results` | Object | N/A | Read-only | Contains the results of attempts to notify the user. | | `notification.results.` `error` | Object | N/A | Read-only | Contains information regarding why a notification failed to send. | | `notification.results.` `method` | String | N/A | Read-only | Method used in the attempt to notify the user; can be `EMAIL` or `SMS`. | | `notification.results.` `notification.id` | String | N/A | Read-only | Identifier (UUID) of the notification that was sent. | | `notification.results.` `sent` | Boolean | N/A | Read-only | Whether the notification was successfully sent. | | `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 | Required | 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 | N/A | Read-only | Status of the user credential. Can be `ISSUED`, `PENDING`, `REVOKED`, or `DELETED`. | | `title` | String | N/A | Read-only | Returned as defined in the credential type. | | `updatedAt` | DateTime | N/A | Read-only | Date and time the credential type was last updated; can be null. | | `user.id` | String | Required | Immutable | Identifier (UUID) of the user. Supplied in the endpoint. | 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. Although `notification.template` is immutable, [Update a User Credential](user-credentials/update-a-user-credential.html) can change `notification.template` on a specific credential for its life span. ### data object data model | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `data` object is only used in the request body and is ephemeral - it is used to create the credential and discarded. It is not returned with [Read All User Credentials](user-credentials/read-all-user-credentials.html) or [Read One User Credential](user-credentials/read-one-user-credential.html). This permits, for example, submission of sensitive information that customers do not want to store in a user directory.Because the `data` is not stored, the user credential can only be provisioned to digital wallets that are already paired. If no paired digital wallets exist on the user when the user credential is created or updated, the credential is not issued and an error message is returned. | The `data` object can only be used for [Credential Types](credential-types.html) where its `management.mode` is `MANAGED`. Individual fields in `data` can only be used where the corresponding credential type's `metadata.fields.type` is `Alphanumeric Text`. If the corresponding credential type's `metadata.fields.value` is valued, that value represents a default for the field and can be overridden in [Create a User Credential](user-credentials/create-user-credential.html) or [Update a User Credential](user-credentials/update-a-user-credential.html) API requests. The `data` object contains any number of keys, where the key is the `title` in `metadata.fields` that represents a specific attribute of the credential type required by the issuer. For example, an insurance company might have a `metadata.fields.title` of `Endorsements` and the corresponding `data` key would be `Endorsements`. These `data` fields must match the `metadata.fields` defined for the credential type in `credentialType.id`. For more information on fields, refer to the `fields` object in [metadata object data model](credential-types.html#credentialing-metadata-object-data-model) and the data types in [fields.type types](credential-types.html#credentialing-fields-type-types). Whether any given `data.` is required or optional depends on the corresponding `fields.required` and `fields.value` in the [metadata object](credential-types.html#credentialing-metadata-object-data-model) of the credential type. A `data.` is required when `fields.required` is `true` and no `fields.value` exists and optional when `fields.required` is `false` or when `fields.value` has a value. ## Provisioned Credentials data model (credential) This object is shared with [digital wallets](digital-wallets.html#provisioned-credentials-data-model-wallet). It is returned only with [Read One User Credential Wallets](user-credentials/read-one-user-credential-wallets.html) and [Read One Digital Wallet Credentials](digital-wallets/read-one-digital-wallet-credentials.html). The former returns all digital wallets associated with the specified user credential, the latter returns all user credentials associated with the specified digital wallet. | Property | Type | Required? | Mutable? | Description | | -------------------------- | --------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `claimReference` | Object | N/A | Read-only | The serialized JSON object used to create the ClaimReference object returned. This is needed to revoke an issued credential. | | `createdAt` | DateTime | N/A | Read-only | Date and time the credential was provisioned. | | `credential.id` | String | N/A | Read-only | Identifier (UUID) of the user credential associated with the provisioned credential. | | `digitalWallet.id` | String | N/A | Read-only | Identifier (UUID) of the digital wallet associated with the provisioned credential. | | `environment.id` | String | N/A | Read-only | Identifier (UUID) of the environment associated with the provisioned credential. | | `expiresAt` | Date | N/A | Read-only | The date that the provisioned credential expires. If this value is null, the provisioned credential never expires. | | `id` | String | N/A | Read-only | Identifier (UUID) of the provisioned credential. | | `status` | String | N/A | Read-only | Status of the provisioned credential. Can be `CREATED`, `ACCEPTED`, `REJECTED`, `REVOKED`, or `DELETED`. | | `user.id` | String | N/A | Read-only | Identifier (UUID) of the user associated with the provisioned credential. | | `walletActions` | Object\[] | N/A | Read-only | Array of actions taken regarding the provisioned credential. | | `walletActions.action` | String | N/A | Read-only | Action taken regarding the provisioned credential; can be `CREDENTIAL_ACCEPTED`, `CREDENTIAL_REJECTED`, `CREDENTIAL_REVOKED`, or `CREDENTIAL_DELETED`. | | `walletActions.occurredAt` | DateTime | N/A | Read-only | Date and time that the action 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. |