--- title: Configuring a REST API datastore description: Create a REST API datastore to interact with a REST API. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_config_rest_api_datastore canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_config_rest_api_datastore.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: March 20, 2026 section_ids: steps: Steps result: Result: example: Example related-links: Related links --- # Configuring a REST API datastore Create a REST API datastore to interact with a REST API. ## Steps 1. Go to **System > Data & Credential Stores > Data Stores**. 2. On the **Data Stores** window, click **Add New Data Store**. 3. On the **Data Store Type** tab, type a name for the datastore. 4. From the **Type** list, select **Rest API**. 5. (Optional) To mask attribute values returned from this datastore in PingFederate logs, select the **Mask Values in Log** checkbox. 6. Click **Next**. 7. On the **Configure Data Store Instance** tab, click **Add a new row to 'Base URLS and Tags'**. 1. Enter the **Base URL** of the data source offering REST API access to its data. You can enter multiple base URLs. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------ | | | If you configure multiple URLs, nodes use the first URL with a tag that matches one of the `node.tags` in the `run.properties` file. | 2. (Optional) Enter one or more tags per base URL. Tags are defined in the `node.tags` property in the `/pingfederate/bin/run.properties` file. For a description of the `node.tags` property, see [Deploying cluster servers](../server_clustering_guide/pf_deploying_cluster_servers.html). In PingFederate deployments that are regional, you can enter one or more tags for a Base URL, which specifies the PingFederate node the datastore should communicate with. If none of the tags match what is defined for the `node.tags` property, the default node is used. The following rules apply to tags: * You must separate multiple tags specified for one node with spaces. * Tags must unique per base datastore. * You can't use a tag more than once per datastore. * Tags are optional. If needed, you can configure a non-default node without tags. Doing this is useful if you aren't yet ready to tag the node, or if you are still in the planning stage but want to enter the address for the node now. 3. Click **Update** under **Action**. 4. Select **Set as Default** under **Action** beside the Base URL and Tags that you want to use as the default. The first Base URL and Tags configured is set as the default automatically. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If the data source exposes multiple paths or requires specific query parameters to retrieve user records, enter the base URL here and then specify the path and query parameters in the attribute source configuration.For more information, see [Specifying data source filters for REST API datastores](pf_specify_resourc_path_for_a_rest_api_datastore.html). | 8. If the data source requires specific HTTP request headers, click **Add a new row to 'HTTP Request Headers'**. | | | | - | -------------------------------------------------------------------------------------------------------------------------- | | | If configured, PingFederate includes the configured HTTP request headers and their values when contacting the data source. | 1. Enter the applicable name and value under **Header Name** and **Header Value**. 2. Click **Update** under **Action**. Repeat these steps to define additional HTTP request headers and their values. 9. Click **Add a new row to 'Attributes'** to define local attribute names and map them to the data returned by the data source. Map each attribute to a path representing an attribute in the JSON response. This path follows the syntax defined in the [JavaScript Object Notation (JSON) Pointer](https://datatracker.ietf.org/doc/html/rfc6901) specification. If you leave the **JSON Response Attribute Path** field blank, the local attribute maps to the full JSON response document. 1. Enter the **Local Attribute** name and **JSON Response Attribute Path**. 2. Click **Update** under **Action**. Repeat these steps to define additional attributes. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Define only the attributes required by other configuration items, such as contract fulfillment or token authorization. Provide meaningful attribute names so that you can easily recognize them at a later time. | 10. Select an **Authentication Method**: | Option | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **None** | PingFederate makes unauthenticated REST API requests to the data source. No credential information is required. This is the default setting. | | **Basic Authentication** | PingFederate authenticates using the HTTP Basic authentication scheme. Enter the required credentials in the **Username** and **Password** fields. | | **Client TLS Certificate** | To support mutual TLS (mTLS), PingFederate authenticates by presenting the client transport layer security (TLS) certificate that you select in the **Client TLS Certificate** list.If you haven't yet created or imported a client certificate, click **SSL Client Keys & Certificates** to do so. Learn more in [Manage SSL client keys and certificates](help_certmanagementtasklet_sslcertauth_certmanagementstate.html). | | **OAuth 2.0 Bearer Token** | PingFederate authenticates by presenting an OAuth 2.0 access token. In this scenario, PingFederate is an OAuth client, specifically a client that uses the client credential or private key JWT grant type to obtain an access token from an authorization server and presents the access token to the data source for authentication. | 11. Select the **HTTP Method** to call the REST API service: **GET**, **POST**, **PUT**, **PATCH** or **DELETE**. All request methods support the JSON and x-www-form-urlencoded body types, among others, but PingFederate can parse only JSON responses. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------ | | | When configuring data source filters for attribute sources and user lookup, you can define the body sent in requests to the REST API data store. | 12. The required authentication fields depend on which **Authentication Method** you selected. The following table describes the fields required for each authentication method: | Field | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Basic Authentication** | | | **Username** | Enter the username for basic authentication | | **Password** | Enter the password for basic authentication | | **Password Reference** | If you're using a configured password manager, enter the secret reference. The format is `OBF:MGR:{secretManagerId}:{secretId}`. Learn more in [Secret managers](pf_secret_managers.html). | | **Client TLS Certificate** | | | **Client TLS Certificate** | Select a certificate in the list. You can manage certificates in the **SSL Client Keys & Certificates** menu. Learn more in [Manage SSL client keys and certificates](help_certmanagementtasklet_sslcertauth_certmanagementstate.html). | | **OAuth 2.0 Bearer Token** | | | **OAuth Authentication Method** | Select one:- **Client Credentials** PingFederate obtains a token using a client ID and client secret pair. - **Private Key JWT** PingFederate obtains a token using a client assertion.The subsequent fields required depend on which OAuth authentication method you choose. | | **Client Credentials** | | | **OAuth Token Endpoint** | Enter a valid URL for the authorization server endpoint. | | **OAuth Scope** (optional) | Enter the scopes to request from the authorization endpoint. Separate scopes with a space. | | **Client ID** | Enter the ID of the client created in the authorization server for authentication. | | **Client Secret** | Enter the secret for the client created in the authorization server for authentication. | | **Secret Reference** | If you're using a configured secret manager, enter the secret reference for the client created in the REST service. The format is `OBF:MGR:{secretManagerId}:{secretId}`. Learn more in [Secret managers](pf_secret_managers.html). | | **Private Key JWT** | | | **OAuth Token Endpoint** | Enter a valid URL for the authorization server endpoint. | | **OAuth Scope** (optional) | Enter the scopes to request from the authorization endpoint. Separate scopes with a space. | | **Client ID** | Enter the ID of the client created in the authorization server for authentication. | | **Use Centralized Signing Key** | Select if you want to use centralized PingFederate signing keys when signing JWT client assertions.When you use this option, the authorization server can retrieve the key it needs to validate the digital signature using the PingFederate `/pf/JWKS` endpoint.This is the recommended approach and is selected by default. Learn more about Centralized Signing Key in [Keys for OAuth and OpenID Connect](help_jwksendpointtasklet_jwksendpointkeysstate.html). | | **JWT Signing Key** (optional) | Select a specific certificate from the PingFederate certificate store to use for signing JWT client assertions. Only do this if you didn't select **Use Centralized Signing Key**. If you haven't created or imported a certificate into PingFederate, click **Manage Signing Certificates** at the bottom of the menu to do so.If you use this option, the authorization server requires the specified JWT signing key to validate the digital signature. | | **JWT Signing Algorithm** | Select an algorithm in the list to use for signing the client assertion. | | **JWT Audience** | Enter an audience claim for the JWT client assertion.The recommended value is the issuer identifier of the client authorization server. | | **JWT Lifetime (Minutes)** | Enter an integer for the lifetime of the JWT client assertion. Default value is `5`. Maximum value is `1440`. | | **JWT Type Header** | Enter the type header value for the JWT client assertion. | | **Not Before Claim** (optional) | When enabled, the JWT client assertion includes an nbf (Not Before) claim backdated by 5 seconds. This provides a buffer to account for clock skew between systems. | 13. (Optional) Click **Show Advanced Fields** to configure additional settings. The following table describes the advanced fields. | Field | Description | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Enable HTTPS Hostname Verification** | Indicates whether to verify that the host name of the data source matches the subject (CN) or one of the subject alternative names (SANs) from the certificate. You should verify the host name for all connections.This checkbox is selected by default. | | **Read Timeout (MS)** | Defines the socket timeout in milliseconds.Enter `0` to set an infinite timeout.Enter a negative integer to use the default value set by the operating system.The default value is `10000` in milliseconds, which is 10 seconds. | | **Connection Timeout (MS)** | Determines the timeout in milliseconds until a connection is established.Enter `0` to set an infinite timeout.Enter `-1` to use the default value set by the operating system.The default value is `10000` in milliseconds, which is 10 seconds. | | **Max Payload Size (KB)** | Defines the maximum allowed size in kilobytes (KB) of the returned JSON response payload.Enter `0` to configure an unrestricted payload size.The default value is `1024` in KB. | | **Retry Request** | Determines whether to retry a user data retrieval request if the data source returns an HTTP status code found in the **Retry Error Codes**.This checkbox is selected by default. | | **Maximum Retries Limit** | Defines the maximum number of retry attempts if the data source returns an HTTP status code found in the **Retry Error Codes**.The default value is `5`. | | **Retry Error Codes** | Enter a comma-separated list of HTTP status codes, for which if received from the data source, PingFederate might retry the request.For example, you can enter 429 for "Too Many Request" or 503 for "Service Unavailable".The default value is `429`. | | **Maximum Connections** | An integer that defines the maximum number of connections that can be open for this datastore. | | **Test Connection URL** | Determines the URL to which PingFederate sends requests to test the datastore connection on the **Actions** tab.When not specified (the default), PingFederate sends requests to the base URL of the datastore. | | **Test Connection Body** | The request body to include in the connection test request. | | **Exclude Default Content-Type From GET Request** | When selected, the default Content-Type header is excluded from GET requests. Custom headers are still included. This checkbox is selected by default. | 14. On the **Actions** tab, verify the datastore configuration. 1. Click **Test Connection** to test the connectivity between PingFederate and the data source. ### Result: The administrative console displays the results returned by the data source. The PingFederate server log might contain additional messages as well. 15. On the **Summary** tab, review your configuration, amend as needed, click **Save** to keep your configuration or click **Cancel** to discard it. ## Example You have two use cases that can leverage user attributes obtained through REST APIs. The data source returns user records in JSON: ```json { "uid": "asmith", "office": { "city": "Denver", "state": "CO", "zipCode": 80202 }, "telephoneNumbers": [ "+1 303-555-1234", "+1 303-555-5678" ], "department": "Engineering" } ``` The first use case requires the user's department, while the second use case requires the first telephone number and the ZIP code. To address both use cases and make the full JSON response available for additional processing, create a REST API datastore with the following attributes. | Local Attribute | JSON Response Attribute Path | | --------------- | ---------------------------- | | Dept | /department | | Telephone | /telephoneNumbers/0 | | Zip | /office/zipCode | | FullResponse | | Once set up, you can fulfill various contracts or configure issuance criteria based on the attribute data from the data source. ## Related links * [Token authorization](../introduction_to_pingfederate/pf_token_auth.html) * [Fulfillment by datastore queries](pf_fulfill_by_datastore_queri.html)