--- title: HTTP services description: Configure HTTP settings to connect PingAuthorize to an HTTP service. component: pingauthorize version: 11.1 page_id: pingauthorize:pingauthorize_policy_administration_guide:paz_http_services canonical_url: https://docs.pingidentity.com/pingauthorize/11.1/pingauthorize_policy_administration_guide/paz_http_services.html llms_txt: https://docs.pingidentity.com/pingauthorize/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: June 29, 2026 section_ids: http-settings: HTTP settings headers: Headers certificate_validation: Certificate validation http_auth_methods: HTTP authentication methods none: None basic: Basic bearer-token: Bearer Token oauth-2-0-client-credentials: OAuth 2.0 (Client Credentials) return_full_response: Return full response response-format: Response format example-detecting-fraud-with-structured-error-routing: "Example: Detecting fraud with structured error routing" trust-framework: Trust Framework policies: Policies --- # HTTP services Configure HTTP settings to connect PingAuthorize to an HTTP service. Before you connect to an HTTP service, you can [add attributes](paz_create_attribute.html) that store values for service settings, such as the endpoint URL for an HTTP request. Storing settings as attributes is useful if the values are dynamic or if you want to use different values during testing. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If the service requires OAuth 2.0 Client Credentials authentication, you must add an attribute that stores the external service's client secret before you configure service settings. You can also add attributes that store other client credentials, such as the client ID and token endpoint. | After configuring the service, test the service connection. To make the service response available in policies, add attributes that [resolve](paz_resolvers.html) against the service and [process](paz_value_processing.html) the response to extract required values. ## HTTP settings HTTP service requests can send and receive text, JSON, and XML content. ![Screen capture showing the Service Type, URL, HTTP Method, Body, and Authentication HTTP service settings.](_images/general-http-service-settings.png) **HTTP settings** | Setting | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Target URL** | The URL for the REST endpoint that the policy decision point (PDP) accesses in the HTTP request.To include an attribute anywhere in the URL, wrap the full name of the attribute in double curly brackets. Because no escaping of attribute values takes place, make certain that this action is completed in the attribute definition to prevent non-valid characters in the URL. | | **HTTP Method** | The action performed in the HTTP request. Options are **GET**, **POST**, **PUT**, **DELETE**, and **HEAD**. | | **Content Type** | The media type of the content in the HTTP request. Options are **application/json**, **application/xml**, **text/html**, and text. | | **Body** | The body to send with the HTTP request. You can include attributes anywhere in the body, with no escaping, by wrapping the full name of the attribute in double curly brackets. | ## Headers You can add any number of custom headers to the request. The header names are fixed strings, but their values can be constants or attribute values. To switch between constant and attribute, toggle **C / A**, which is next to a header value. To prevent invalidation of HTTP service response caches caused by changes to the cache key, you can exclude certain headers that you expect to change from service cache entries. Learn more in [Connecting a service](paz_connecting_a_service.html) and [Service caching](paz_service_caching.html). ## Certificate validation With certificate validation, you can define TLS and Mutual-TLS (M-TLS) certificates and keys when connecting to the TLS (or SSL) based service. When using external PDP mode, you can declare local file-based trust stores and key stores by providing an options file during setup. Learn more in [Specifying custom configuration with an options file](../pingauthorize_server_administration_guide/paz_specify_custom_config_opts_file.html). When using embedded PDP mode, you can declare local file-based trust stores and key stores by assigning trust manager providers and key manager providers to the Policy Decision Service. Learn more in [Deploy policies in a production environment](../pingauthorize_server_administration_guide/paz_create_policies_prod.html). * **Server (TLS)** Applies when validating the certificate or certificate chain sent from the server. You have three options when validating a server certificate: * **No Validation** Skips validating the server certificates and initiates connection without any restriction. * **Default** | | | | - | -------------------------------------------- | | | This option is the default for Server (TLS). | Uses the default trust store provided by the runtime environment. Use this if you're trying to connect to a service that has a certificate issued from a valid certificate authority. * **Custom** Allows the user to define a custom certificate or certificate chain that is stored in a trust store: * **Truststore name** The name given to the trust store in `configuration.yml`. * **Alias** Certificates in the trust stores are mapped by alias. You must set the alias in the trust store to specify which certificate to use for validation. Attributes can be interpolated anywhere in the value. * **Alias password** If the certificate is password protected, it might need to provide the password. Attributes can be interpolated anywhere in the value. * **Client (M-TLS)** Some services might require the client to provide a client certificate when initializing the connection. To provide a client certificate, enable this setting and provide a custom key store to be sent to the service: * **Keystore name** The name given to the key store in `configuration.yml`. * **Alias** Key-value pairs and the certificate entry in the key stores are mapped by alias. You must set the alias in the key store to specify which entry to use for validation. Attributes can be interpolated anywhere in the value. * **Alias password** If the certificate entry is password protected, it might need to provide the password. Attributes can be interpolated anywhere in the value. ## HTTP authentication methods HTTP service requests can use no authentication, basic authentication with a username and password, a bearer token, or the OAuth 2.0 Client Credentials flow. ### None With this method, no authorization header is sent with the HTTP request. This is the default option. ### Basic For basic authentication, provide a username and password. ![Screen capture showing the Username and Password settings for Basic authentication](_images/http-service-basic-auth.png) ### Bearer Token For bearer authentication with a static token, select an attribute that stores the authorization token to send with the HTTP request. ![Screen capture showing the Token selection list for Bearer Token authentication](_images/http-service-bearer-auth.png) ### OAuth 2.0 (Client Credentials) To reduce configuration complexity and time to production when connecting to HTTP services that require OAuth authentication, configure client credentials to exchange for an access token. ![Screen capture showing the Token Endpoint, Scope, Client Id, and Client Secret settings for OAuth 2.0 Client Credentials authentication](_images/http-service-client-cred-auth.png) PingAuthorize manages this authentication process as follows: 1. PingAuthorize requests an access token for the external service by sending client credentials, including any scopes, in a POST request to the authorization server's token endpoint. Credentials are sent in the request body. PingAuthorize always sends credentials in the HTTP request body (`client_secret_post`) and doesn't support using the `Authorization` header (`client_secret_basic`). 2. The authorization server validates the client credentials and provides an access token, which PingAuthorize caches. When the external service no longer accepts this token, PingAuthorize sends another POST request to the token endpoint to obtain a new one. 3. In an HTTP service request, PingAuthorize provides the access token in the `Authorization` header, authenticates with the HTTP service, and retrieves the requested information from the service. Before you configure the following settings, add an attribute that stores the client secret. You can also add attributes that store other client credentials. * **Token Endpoint**: The token endpoint URL for the authorization server that grants an access token. For example, `https://{domain}/oauth*/token`. * **Client Id**: A unique string representing the client identifier. This value can be either a constant or an interpolated attribute to resolve the value at runtime. * **Client Secret**: A Trust Framework attribute that resolves to the client secret. * **Scope** (optional): A comma-separated list of scopes representing the scope of the access request. * **Advanced OAuth Settings** (optional): A list of custom key-value pairs representing additional parameters sent in the body of the token endpoint request. This level of customization is useful when integrating with authorization servers that enforce specific configuration constraints. The keys are fixed strings, but their values can be constants or attribute values. To switch between constant and attribute, toggle **C / A**. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Advanced OAuth settings have the following constraints:- You can define up to 10 key-value pairs. - Keys cannot contain spaces in any position. - You cannot use any of the following values as a key (case-sensitive): * `client_id` * `client_secret` * `scope` * `grant_type` | ## Return full response By default, PingAuthorize treats non-2xx HTTP responses as service failures, which prevent attribute resolution and produce `Indeterminate` decision responses. When you select the **Return Full Response** checkbox for an HTTP service, PingAuthorize passes every service response to the decision engine as a structured object, regardless of status code. This object includes the HTTP status code, response body, and headers. You can use these values in policy expressions to make decisions based on service outcomes and implement custom error-handling logic. ![Screen capture showing the Return Full Response setting for an HTTP service](_images/paz_return_full_response.png) | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When you select **Return Full Response** for HTTP services, PingAuthorize returns non-2xx responses without applying retry or circuit breaker logic. Your authorization policies must determine how to route and handle these responses. | ### Response format With **Return Full Response** selected, every service response resolves to a JSON object with the following structure: ```json { "statusCode": , "body": { "": "" }, "headers": { "": [""] } } ``` * `statusCode` The HTTP status code returned by the service. * `body` The service response body. JSON response bodies are parsed as structured objects that you can inspect with [JSON Path](paz_value_processing.html#json_path_processor). Non-JSON bodies are embedded as a raw string. An empty response body produces an empty string (`""`). When you use attribute resolvers to inspect the service response body, you must use the `body.` prefix. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Selecting **Return Full Response** for a service changes the format for all responses, including 2xx responses.You must update any existing processors that inspect the response body to include the `body.` prefix. For example, if a service returns `{ "userId": "abc123" }` by default, the JSON Path expression to extract `userId` changes from `$.userId` to `$.body.userId`. Learn more in [Resolvers](paz_resolvers.html). | * `headers` A map of response header names to their values. Header names are normalized to lowercase. Each header value is a list of strings to accommodate headers that appear multiple times in a response. For headers that appear once, use the path `$.headers[''][0]` to extract the first value. ### Example: Detecting fraud with structured error routing Consider an online banking policy that uses **Return Full Response** to handle multiple outcomes from a fraud scoring service, including structured 4xx error responses that carry actionable data. A payment authorization flow calls a third-party fraud scoring service for every transaction. The service can return three distinct responses depending on the transaction and service availability: * 200 OK Transaction scored successfully: ```json { "transactionId": "TXN-98765", "riskScore": 67, "recommendation": "review" } ``` * 422 Unprocessable Entity Insufficient transaction history: ```json { "code": "INSUFFICIENT_DATA", "message": "Transaction history too limited to score", "minimumTransactionsRequired": 5 } ``` * 503 Service Unavailable Fraud scoring service temporarily unavailable: ```json { "error": "service_unavailable", "retryAfter": 30 } ``` Without **Return Full Response** selected, the 422 and 503 responses both cause a service failure and produce `Indeterminate` decisions. The 422 body, which explains that the account is too new to score and should be routed to manual review rather than denied, is never available for attribute resolution because of the failure. With **Return Full Response** selected, PingAuthorize passes every service response to the decision engine, regardless of status code. The full structured response objects for the previous default responses look as follows: * 200 OK ```json { "statusCode": 200, "body": { "transactionId": "TXN-98765", "riskScore": 67, "recommendation": "review" }, "headers": { "content-type": ["application/json"] } } ``` * 422 Unprocessable Entity ```json { "statusCode": 422, "body": { "code": "INSUFFICIENT_DATA", "message": "Transaction history too limited to score", "minimumTransactionsRequired": 5 }, "headers": { "content-type": ["application/json"] } } ``` * 503 Service Unavailable ```json { "statusCode": 503, "body": { "error": "service_unavailable", "retryAfter": 30 }, "headers": { "content-type": ["application/json"] } } ``` #### Trust Framework The following **Status code** attribute resolves from the **Fraud check** service's status code: ![Screen capture of a status code attribute that resolves from the fraud service.](_images/paz-status-code-attribute.png) The following **Error code** attribute resolves from the **Fraud check** service's `code` response field: ![Screen capture of an error code attribute that resolves from the fraud service.](_images/paz-error-code-attribute.png) The following **Risk score** attribute resolves from the **Fraud check** service's `riskScore` response field: ![Screen capture of a risk score attribute that resolves from the fraud service.](_images/paz-risk-score-attribute.png) Because all three attributes resolve against the same service call, PingAuthorize makes a single request to the fraud scoring service per decision evaluation, and each attribute extracts its value from the shared response object. #### Policies With these attributes, authorization policies can make decisions on service outcomes without treating non-2xx responses as failures. For example, the following **Approve transaction** policy returns a `Permit` decision when the service returns a 200 status code and a risk score below 70: ![Screen capture of a policy that permits transactions with 200 status codes and low risk scores.](_images/paz_approve_fraud.png) The following **Deny transaction** policy returns a `Deny` decision when the service returns a 422 status code and an `INSUFFICIENT_DATA` error code: ![Screen capture of a policy that denies transactions with 422 status codes and insufficient risk data.](_images/paz_deny_fraud_policy.png) Together, these policies let the payment authorization flow respond appropriately to the fraud scoring service without falling back to a generic `Indeterminate` decision.