---
title: API security gateway authentication
description: The API security gateway authenticates requests through bearer tokens by default, and you can configure it to handle authentication according to your preferences.
component: pingauthorize
version: 11.0
page_id: pingauthorize:pingauthorize_server_administration_guide:paz_api_security_gw_authn
canonical_url: https://docs.pingidentity.com/pingauthorize/11.0/pingauthorize_server_administration_guide/paz_api_security_gw_authn.html
revdate: January 28, 2025
section_ids:
  example: Example
  example-2: Example
---

# API security gateway authentication

The API security gateway authenticates requests through bearer tokens by default, and you can configure it to handle authentication according to your preferences.

Although the gateway doesn't require the authentication of requests, the default policy set requires bearer token authentication.

To support this, the gateway uses the configured access token validators to evaluate bearer tokens that are included in incoming requests. The validation result is supplied to the policy request in the `HttpRequest.AccessToken` attribute, and the user identity associated with the token is provided in the `TokenOwner` attribute.

Policies use this authentication information to affect the processing of requests and responses. For example, a policy in the default policy set requires that all requests are made with an active access token.

```
Rule: Deny if HttpRequest.AccessToken.active Equals false

Statement:
  Code: denied-reason
  Applies To: Deny
  Payload: {"status":401, "message": "invalid_token", "detail":"Access token is expired or otherwise invalid"}
```

Gateway API Endpoints include the following configuration properties to specify how client authentication is handled:

* `http-auth-evaluation-behavior`

  Determines whether the Gateway API Endpoint evaluates or modifies the HTTP authentication scheme and whether this scheme is forwarded to the API server.

  This property accepts the following values:

  * `do-not-evaluate`

    The Gateway API Endpoint doesn't evaluate or modify the HTTP authentication scheme. This can be useful when implementing an authentication scheme that doesn't evaluate bearer tokens, such as MTLS.

    If the client request includes an `Authorization` header, the PingAuthorize Server forwards the unmodified header to the external API server.

    |   |                                                                                                                                                                                                                                                           |
    | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    |   | If you specify this value, policies protecting this endpoint should not enforce constraints on request authentication, such as the validity of the access token. The default policy snapshot enforces such a constraint in the `Token Validation` policy. |

  * `evaluate-and-forward`

    The Gateway API Endpoint evaluates the provided authentication credentials and makes authentication information available for policy evaluation. If the client request includes an `Authorization` header, the PingAuthorize Server forwards the unmodified header to the external API server unless a policy decision directs otherwise.

    This value is set by default.

  * `evaluate-and-discard`

    The Gateway API Endpoint evaluates the provided authentication credentials and makes authentication information available for policy evaluation. If the client request includes an `Authorization` header, the PingAuthorize Server removes this header before forwarding the request to the external API server.

  * `evaluate-and-replace`

    The Gateway API Endpoint evaluates the provided authentication credentials and makes authentication information available for policy evaluation. If the client request includes an `Authorization` header, the PingAuthorize Server replaces this header with one containing the basic authentication credentials defined for the external API server.

    |   |                                                                                                                                |
    | - | ------------------------------------------------------------------------------------------------------------------------------ |
    |   | If you specify this value, make sure your authorization policies enforce an appropriate level of authorization for the client. |

  ## Example

  ```
  bin/dsconfig set-gateway-api-endpoint-prop \
    --endpoint-name <your-endpoint-name> \
    --set http-auth-evaluation-behavior:evaluate-and-replace
  ```

  In this example, the `http-auth-evaluation-behavior` property is set to `evaluate-and-replace`.

* `access-token-validator`

  Sets the access token validators that the Gateway API Endpoint uses. By default, this property has no value, and the Gateway API Endpoint can evaluate every bearer token by using each access token validator that is configured on the server. To constrain the set of access token validators that a Gateway API Endpoint uses, set this property to use one or more specific values.

  If `http-auth-evaluation-behavior` is set to `do-not-evaluate`, this setting is ignored.

  ## Example

  ```
  bin/dsconfig set-gateway-api-endpoint-prop \
    --endpoint-name <your-endpoint-name> \
    --set access-token-validator:example-token-validator
  ```

  In this example, the `access-token-validator` property is set to `example-token-validator`.