--- title: Configuring a REST API datastore description: To retrieve attribute data from a JSON-based REST API, you must first create a REST API datastore. component: pingfederate version: 12.2 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: February 26, 2026 superseded_by: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_config_rest_api_datastore.html section_ids: steps: Steps choose-from: Choose from: choose-from-2: Choose from: result: Result: example: Example related-links: Related links --- # Configuring a REST API datastore To retrieve attribute data from a JSON-based REST API, you must first create a REST API datastore. ## 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 cannot 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 are not 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. You must define at least one attribute. 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 via the HTTP Basic authentication scheme. Enter the required credentials in the **Username** and **Password** fields. | | **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 grant type to obtain access token from an authorization server and presents the access token to the data source for authentication. Enter the client credentials in the **Client ID** and **Client Secret** fields. Then enter the token endpoint URL at the authorization server and the applicable scope (or scopes) in the **OAuth Token Endpoint** and **OAuth Scope** 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. For more information, see [Manage SSL client keys and certificates](help_certmanagementtasklet_sslcertauth_certmanagementstate.html). | 11. Select the **HTTP Method** to call the REST API service: **GET** or **POST**. Both 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 GET or POST requests to the REST API data store. | 12. If you selected **Basic Authentication**, configure the following: 1. In the **Username** field, enter a username. 2. Choose one of the following: ### Choose from: * In the **Password** field, enter a password. * If you're using a secret manager, enter the secret reference in the **Password Reference** field. The format is `OBF:MGR:{secretManagerId}:{secretId}`. Learn more in [Secret managers](pf_secret_managers.html). 13. If you selected **OAuth 2.0 Bearer Token**, configure the following: 1. In the **OAuth Token Endpoint** field, enter a valid URL for the authorization server endpoint. 2. (optional) In the **OAuth Scope** field, enter the scopes to request from the authorization endpoint. Separate scopes with a space. Learn more in [Scopes and scope management](pf_scopes_and_scope_management.html). 3. In the **Client ID** field, enter the ID of the client created in the REST service for authentication. 4. Choose one of the following: ### Choose from: * In the **Client Secret** field, enter the secret for the client created in the REST service for authentication. * If you're using a 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). 14. If you selected **Client TLS Certificate**, select a certificate in the **Client TLS Certificate** list. You can manage certificates in the **Trusted CAs** menu. Learn more in [Manage trusted certificate authorities](help_certmanagementtasklet_trustedcas_certmanagementstate.html). 15. (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 hostname of the data source matches the subject (CN) or one of the subject alternative names (SANs) from the certificate.+ You should verify the hostname 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. | 16. (Optional) To mask attribute values returned through this datastore in the PingFederate log, select the **Mask Values in Log** checkbox. This checkbox is visible only when editing an existing datastore and is cleared by default. 17. 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 may contain additional messages as well. \+ 1. Review the results. 2. (Optional) Click **Reset** and repeat the test. 18. 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, create a REST API datastore with the following attributes. | Local Attribute | JSON Response Attribute Path | | --------------- | ---------------------------- | | Dept | /department | | Telephone | /telephoneNumbers/0 | | Zip | /office/zipCode | 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)