---
title: ClientCredentialsOAuth2ClientFilter
description: Configure ClientCredentialsOAuth2ClientFilter to authenticate OAuth 2.0 clients using the client_credentials grant type and inject access tokens into requests
component: pinggateway
version: 2024.11
page_id: pinggateway:reference:ClientCredentialsOAuth2ClientFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/ClientCredentialsOAuth2ClientFilter.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2026-06-02T09:47:34Z
superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/ClientCredentialsOAuth2ClientFilter.html
section_ids:
  ClientCredentialClientCredentialsOAuth2ClientFilter-usage: Usage
  ClientCredentialsOAuth2ClientFilter-properties: Properties
  ClientCredentialsOAuth2ClientFilter-example: Examples
  ClientCredentialsOAuth2ClientFilter-moreinfo: More information
---

# ClientCredentialsOAuth2ClientFilter

Authenticates OAuth 2.0 clients by using the client's OAuth 2.0 credentials to obtain an access token from an Authorization Server, and injecting the access token into the inbound request as a Bearer Authorization header. The access token is valid for the configured scopes.

The ClientCredentialsOAuth2ClientFilter obtains the client's access token by using the `client_credentials` grant type. Client authentication is provided by the `endpointHandler` property, which uses a client authentication filter, such as [ClientSecretBasicAuthenticationFilter](ClientSecretBasicAuthenticationFilter.html). The filter refreshes the access token as required.

Use the ClientCredentialsOAuth2ClientFilter in a service-to-service context, where services need to access resources protected by OAuth 2.0.

## Usage

```json
{
  "name": string,
  "type": "ClientCredentialsOAuth2ClientFilter",
  "config": {
    "secretsProvider": SecretsProvider reference,
    "tokenEndpoint": configuration expression<url>,
    "scopes": [ configuration expression<string>, ... ],
    "endpointHandler": Handler reference,
    "clientId": configuration expression<sting>, //deprecated
    "clientSecretId": configuration expression<secret-id>, //deprecated
    "handler": Handler reference //deprecated
  }
}
```

## Properties

* `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required*

  The [SecretsProvider](SecretsProvider.html) to query for passwords and cryptographic keys.

- `"tokenEndpoint"`: *configuration expression<[url](preface.html#definition-url)>, required*

  The URL to the Authorization Server's OAuth 2.0 token endpoint.

- `"scopes"`: *array of configuration expression<[strings](preface.html#definition-string)>, optional*

  Array of scope strings to request from the Authorization Server.

  Default: Empty, request no scopes.

- `"endpointHandler"`: *Handler [reference](preface.html#definition-reference), optional*

  The Handler to exchange tokens on the authorization endpoint.

  Configure this property as a [Chain](Chain.html), using one of the following client authentication filters:

  * [ClientSecretBasicAuthenticationFilter](ClientSecretBasicAuthenticationFilter.html)

  * [ClientSecretPostAuthenticationFilter](ClientSecretPostAuthenticationFilter.html)

  * [PrivateKeyJwtClientAuthenticationFilter](PrivateKeyJwtClientAuthenticationFilter.html)

  ```json
  {
    "name": "myHandler",
    "type": "Chain",
    "config": {
      "handler": "ForgeRockClientHandler",
      "filters": [
        {
          "type": "ClientSecretBasicAuthenticationFilter",
          "config": {
            "clientId": "myConfidentialClient",
            "clientSecretId": "my.client.secret.id",
            "secretsProvider" : "mySystemAndEnvSecretStore",
          }
        }
      ]
    }
  }
  ```

  Default: ForgeRockClientHandler

- `"clientId"`: *configuration expression\<string>, required*

  |   |                                                                                                                                                                                                                      |
  | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  |   | This property is deprecated. Use `endpointHandler` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. |

  The ID of the OAuth 2.0 client registered with the Authorization Server.

  If you use the deprecated properties, provide `clientId`, `clientSecretId` to obtain the client secret, which authenticates using the `client_secret_basic` method.

- `"clientSecretId"`: *configuration expression\<secret-id>, required*

  |   |                                                                                                                                                                                                                      |
  | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  |   | This property is deprecated. Use `endpointHandler` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. |

  The ID to use when querying the `secretsProvider` for the client secret.

  This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types).

- `"handler"`: *Handler reference or inline Handler declaration, optional*

  |   |                                                                                                                                                                                                                      |
  | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  |   | This property is deprecated. Use `endpointHandler` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. |

  The Handler to use to access the Authorization Server's OAuth 2.0 token endpoint. Provide either the name of a handler object defined in the heap or specify a handler object inline.

  Default: ClientHandler

## Examples

For an example, refer to [Client credentials grant](../gateway-guide/oauth2-clientcredentials.html).

## More information

[org.forgerock.openig.filter.oauth2.client.ClientCredentialsOAuth2ClientFilterHeaplet](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/client/ClientCredentialsOAuth2ClientFilterHeaplet.html)

[org.forgerock.openig.filter.oauth2.OAuth2ResourceServerFilterHeaplet](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/OAuth2ResourceServerFilterHeaplet.html)

[OAuth2ResourceServerFilter](OAuth2ResourceServerFilter.html)

[The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749)

[The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://www.rfc-editor.org/rfc/rfc6750)