Use the Credential Issuers operations to retrieve or update the credential issuer information. A credential issuer profile, which enables issuance of credentials, is automatically created when the credential service is added to an environment.

Credential Issuers data model

The logo and name can be shown to the user when indicating the credential issuer by the wallet app using using the PingOne Neo Native SDKs with getIssuerMetadata for Android and getCredentialIssuerMetadataFromClaim(_:) for iOS.

Response codes

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

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

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.

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.

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

fields.type types

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

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

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:

• Read Credential Issuance Rule Staged Changes

• Read Credential Issuance Rule Usage Counts

• Read Credential Issuance Rule Usage Details

• Apply Credential Issuance Rule Staged Changes

Credential Issuance Rules data model

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

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.

Credential Issuance Rules usage counts data model

Credential Issuance Rules usage details data model

Credential Issuance Rules errors object

Credential Issuance Rules staged changes error codes

Response codes

The digital wallet apps service controls the relationship between the customer's digital wallet app, which communicates with users' digital wallets, and a customer's PingOne application.

Digital wallet app data model

The Digital Wallet service controls the relationship between a user's phone wallet app, which uses the Wallet SDK, and the customer's PingOne application. It also offers notifications when the PingOne application communicates with the user's Wallet SDK. Settings on the Digital Wallet configure sending push notifications from PingOne Credentials to the Wallet SDK of the user.

In the normal digital wallet pairing use case, you use Create Digital Wallet to create the Digital Wallet without the applicationInstance.id and a pairing session is created. The Digital Wallet service uses the digital_wallet_pairing notification template to send the pairing session URL (refer to appOpen.href in the response) to the user via email or text or you show a QR code (refer to qrUrl.href in the response) of the pairing session URL to the user. When the user opens the URL, it opens your app or takes them to a page with instructions on how to install the app. When the app opens the URL, it shares its applicationInstance.id with the service using the Wallet SDK.

Alternatively, you send the applicationInstance.id when you create the Digital Wallet. For example, if you have the user install your app, the user authenticates with your servers. When your app is installed, it creates an application instance. Since the app knows who the user is, the app sends its application instance identifier to your server and then your application sends the applicationInstance.id to the service when creating or updating the Digital Wallet. This creates a Digital Wallet with a known application instance identifier. Activation of the Digital Wallet requires sending some device data, such as SDK version and application bundle ID or package name, to PingOne Credentials:

1. The service creates a pairing session and sends a pairing request message to the device.
2. The Wallet SDK receives this request and the app approves the request.
3. The Wallet SDK sends the device data to PingOne Credentials, which activates the Digital Wallet.

Digital wallet data model

Pairing attempt errors

The digital wallet service uses the digital_wallet_pairing notification template to send the pairing session URL to the user via email or SMS text. The notification.template object can define a variant and locale for the notification, if needed.

Provisioned Credentials data model (wallet)

This object is shared with user credentials. It is returned only with Read One Digital Wallet Credentials and Read One User Credential Wallets. The former returns all user credentials associated with the specified digital wallet, the latter returns all digital wallets associated with the specified user credential.

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:

• if management.mode is AUTOMATIC, create a credential issuance rule and the service issues the credential to all users who match the rule.

• if management.mode is MANAGED, create a credential type (managed) or update a user credential and the service issues the credential to that user.

Regardless of management.mode, you can revoke a user credential, read all user credentials, read one user credential, or read one user credential wallets.

User Credentials data model

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 can change notification.template on a specific credential for its life span.

data object data model

The data object can only be used for Credential Types 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 or Update a User Credential 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 Medical Limitations and the corresponding data key would be Medical Limitations. 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 and the data types in fields.type types.

Whether any given data.<field> is required or optional depends on the corresponding fields.required and fields.value in the metadata object of the credential type. A data.<field> 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. It is returned only with Read One User Credential Wallets and Read One Digital Wallet Credentials. The former returns all digital wallets associated with the specified user credential, the latter returns all user credentials associated with the specified digital wallet.

Response codes

The Credential Verification service receives, and responds to, requests for credential verification using Decentralized Identity Foundation Java Web Token Verifiable Credentials Presentation Profile (DIF JWT-VC Profile). The profile uses such open standards as:

• World Wide Web Consortium (W3C) Decentralized Identifiers (DID) for core architecture, data model, and representations

• W3C Verifiable Credentials Data Model for the presentation data model

• DIF Presentation Exchange for credential request

• OpenID for Verifiable Presentations (OpenID4VP ID1) as the base protocol for transportation

Use of these standards provides interoperability with any app that complies with DIF JWT-VC Profile.

The service can also use PingOne native protocols. The PingOne native protocol only works with apps that use the PingOne Neo Native SDKs, which has more features but is restricted to only supported apps.

Credential Verifications session data model

The digital wallet service uses the credential_verification notification template to send a push notification to a digital wallet when a Create Credential Verification Session (NATIVE - Push Notification) is created. The notification.template object can define a variant and locale for the notification, if needed.

If issuerFilter.environmentIds is submitted, the service searches all listed environments for the issuer of the presented credential. If the user presents a credential that is not from one of these issuers, the verification fails with status of VERIFICATION_FAILED.

If issuerFilter.dids is submitted and protocol is OPENID4VP, the service searches all listed decentralized identifiers (DID) for the issuer of the presented credential. If the user presents a credential that is not from one of these issuers, the verification fails with status of VERIFICATION_FAILED.

This issuerFilter.dids typically contains decentralized identifiers for issuers that are not using PingOne Credentials for JWT-VC issuance. The service supports these three DID methods:

• did:web - https://w3c-ccg.github.io/did-method-web/

• did:jwk - https://github.com/quartzjer/did-jwk/blob/main/spec.md

• did:ion - https://identity.foundation/ion/ (The service supports only long-form URIs for this method)

Credential Verifications credential data data model

Credential Verifications session data data model

Credential Verifications errors object data model

Credential Verifications error codes

Response codes

If you want to start building your own workflows with PingOne APIs, the Workflow Library provides step-by-step workflows with linked Postman collections to help you start using the PingOne APIs in your Postman environment. For information about how PingOne secures APIs, resources, and data, and what you can do to implement security measures for your PingOne deployment and applications, refer to Platform security.

If you're new to PingOne and have not set up your test environment, refer to PingOne for Developers Getting Started. This guide helps you get an admin access token, which is required to make API calls to PingOne Credentials API resources.

PingOne API domains

This section discusses how PingOne API regional endpoints are entered in the domain name system (DNS). In DNS, and in our endpoints, the domain part of the uniform resource locator (URL) comprises three parts separated by periods, such as api.pingone.com: one of our service-specific subdomains, our PingOne domain name of pingone, and one of our top level domains.

We use Postman variables to manage this variety of domain parts in PingOne API endpoints. The later discussion is correct regarding the domain part that the variables evaluate to. However, to ease maintenance, the Postman environment template you get when you download a collection uses variables to isolate the TLD from the rest of the domain part and to isolate the domain part from the rest of the endpoint.

The environment template has a path variable for each subdomain. Each path variable uses another variable, {{tld}}, for the top level domain (TLD). Such as https://api.pingone.com/v1 for {{apiPath}}. The tld variable is first in the environment template that you downloaded.

The table below shows the top level domain value for each region. To change your region, simply change the default {{tld}} value from com to your region's TLD.

The PingOne API includes the following domains:

The {{...Path}} variable in the sample requests stand for the PingOne service endpoint. Refer to Public endpoints in the PingOne for Developers Foundations guide for more information.

The Try a Request feature

Our documentation for the PingOne APIs includes an interactive Try a Request feature. Try a Request enables you to configure and send a PingOne API request and get a response from within the documentation. This is a quick way to interactively test a PingOne API request without needing to use either Postman or the command line.

Requests in Authentication and Authorization APIs do not have the Try a Request feature due to a Cross-Origin Resource Sharing (CORS) constraint.

Calling the PingOne APIs from the command line

Each PingOne API request in the documentation includes an example request and response. By default, the example request is displayed using cURL. However, a number of coding languages are available in the associated drop-down list. If you want to run a request from the command line, you can select the coding language and copy the displayed request. You'll need to replace any variables in the request with the appropriate values before running the request.

Using Postman collection-level authorization

Most APIs require authorization to ensure that client requests access data securely. Postman can pass along whatever authorization details necessary for the method demanded by the endpoint. You can manually include authorization data in the header, body, or as parameters to a request. However, the easiest way is to use the Authorization tab in Postman. Select an authorization Type on that tab and Postman offers a dialog to gather the information required by that Type. When you run a request, Postman uses the information from the Authorization tab to automatically add the necessary authorization header, body, or parameters to the request. Postman offers the Authorization tab on requests, folders, and collections.

In PingOne collections, the authorization method is defined at the collection level. Only those requests that require a specific authorization method have authorization defined on the request (roughly 10% of PingOne requests). This allows you to easily change the authorization used for most requests. Refer to Postman Collection-Level Authorization for more information.

We use Postman to create our PingOne Credentials API docs, and have supplied our Postman collections for you to download. There's also an accompanying Postman Environment template already populated with the variables used in the collections.

If you aren't currently using Postman, you can install the free version. Refer to Download Postman to install Postman, either locally, or in your browser.

Refer to The PingOne Credentials API Postman collections for the collections you can download or fork.

For more information about our Postman environment variables, refer to The PingOne Postman environment template.

You'll also find all of the Postman collections for our documented PingOne use cases in our Workflow Library.

You can get the PingOne Credentials API Postman collection by following either of these methods for retrieving a Postman collection into your workspace:

1. Fork the collection into your workspace. Postman retains an association between the source and your fork. If we update the source collection, you can pull those changes into the fork in your workspace.

2. Import the collection into your workspace. This is a one-time transfer and retains no association to the source collection.

To retrieve a collection

Refer to The PingOne Credentials API collections on this page.

1. Click the collection's Run In Postman button.

2. At the prompt, click Fork Collection at the bottom of the dialog or click import a copy near the bottom of the dialog.

   Note: You need to be logged in to your Postman account to retrieve the collection.

   

3. Follow the on-screen instructions to fork or import the collection. You're prompted to select a Postman workspace for the retrieved collection.

When you fork a Postman collection, you create a copy of it in a selected workspace. Forking a collection creates a linked version that synchronizes with its source collection. This synchronization is apparent when you click the three dots icon on the forked collection - you'll see Pull changes on the context menu. When you click Pull changes, Postman compares the fork to the source collection. If changes are available, you can pull those changes into your fork. If you also elect to watch the collection, you'll receive notifications when the source changes.

If you import a collection, a copy is created in the selected workspace with no link back to the source. The collection is static. This may be desirable for some use cases. For example, if you intend to keep and use only some requests in a collection, a link back to the source is not needed.

You're not limited to choosing one method or the other. You can fork a copy to track the source and import a copy for experimentation, if you like.

The PingOne Credentials API collections

These Postman collections include requests for all create, read, update, and delete (CRUD) operations for the PingOne Credentials APIs.

Collection	Description	Retrieve
PingOne Credentials	Postman requests for the PingOne Credentials API. Includes all environment variables. No example responses to make it easy to get started.
PingOne Credentials	Postman requests for the PingOne Credentials API. Includes all PingOne Platform API Reference documentation and example responses. No environment variables are included.

For more information about the Postman environment variables included when you download or fork one of our Postman collections, refer to The PingOne Postman environment template.

Our Postman collections use variables in the request URLs to specify the UUIDs for PingOne resources. When you click the Run in Postman button for a collection, these environment variables are included in your download or fork. Use these environment variables as a template to assign your PingOne resource UUIDs with the common variables used in many of the requests.

For more information about using Postman environments, refer to the following topic in the Postman documentation: Environments in Postman.

POST requests in the PingOne Credentials API Postman collections that create a resource and return a resource ID include a Postman script. This script automatically adds a resource variable to your active Postman environment, and uses the newly created ID as the value.

For example, the following request creates a new Credentials variable. This request URL contains variables for the API path and environment ID:

POST {{apiPath}}/environments/{{envID}}/variables

To run this request, you must ensure the {{apiPath}} in the Postman environment template has the regional top-level domain (TLD) associated with your organization. Refer to Variables you must value for more information.

Almost every request in PingOne requires an environment ID. If you are working primarily in one environment for testing purposes, you'll want to add your environment's UUID to your active Postman environment as the value for the {{envID}} variable.

Requests to PingOne Management API endpoints require a valid access token to authenticate the request. In the PingOne Postman collections, the token value is represented in the Postman environment template as the variable {{accessToken}}.

With the {{tld}} and {{envID}} variables defined in your Postman template, and with a valid token value defined in the {{accessToken}} variable, you can run the request shown above:

POST {{apiPath}}/environments/{{envID}}/variables

If the request is successful, Postman adds a {{variableID}} variable to the current Postman environment automatically, and associates the new user's id property value (the UUID of the new user) with this variable.

Notes about environment variables and security

It's important to understand how Postman allows you to Store and reuse values using variables. Postman has two values for each environment variable: an Initial value and a Current value. You'll want to pay particular attention to differences between Initial and current values. Initial values are saved to Postman's cloud, and available to anyone who has access to the environment. Current values are saved only locally and available only to you. Postman uses only the current value in requests. If an environment variable has an initial value but no current value, Postman doesn't copy it to the current value or use the initial value in the request, the request simply fails. In this case, you need to manually copy the initial value to the current value.

When you create a new variable with an initial value and save the environment, Postman autofills the current value. However, that is the only time that Postman autofills the current value. If you subsequently delete the current value, the variable is no longer valued in a request.

Saving initial values to the Postman cloud impacts security. These initial values are available to anyone who has access to the workspace. If a workspace is public, you have a security issue.

Postman's recommended solution to exposing secrets is to Store secrets in your Postman Vault. Remember that Postman uses only current values in requests.

Variables you must value

When you download or fork a PingOne Postman collection, your workspace receives a set of Postman environment variables for you to use as a template. The variables that represent a resource in PingOne automatically receive a value when you create a new PingOne resource using Postman. Our script associated with the request (shown on the request's Scripts tab) inserts the identifier of the resource it creates as the value of the variable associated with that resource. However, some variables essential to using Postman with PingOne do not have their values inserted automatically. You must manually add the correct value to these variables before making any requests in Postman: