---
schema_version: "1"
id: 96ad45ab472c624cabc80239020db6209a5fbefc145cac7fbecd047b5618e3c6
title: Using OAuth 2.0 Token Introspection Library Functions
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/pdk/latest/policies-pdk-configure-features-token-introspection.md
canonical_url: https://docs.mulesoft.com/pdk/latest/policies-pdk-configure-features-token-introspection
source_site: docs.mulesoft.com
content_type: documentation
content_hash: cc87383177d328da1dd8713efcd26959450483cffcfb77455c0f12d8f0e0f541
description: MuleSoft Documentation Site
release: "1.10"
latest: true
---
---
product: Omni Gateway Policy Development Kit (PDK)
version: 1.10
is-latest-version: true
---

# Using OAuth 2.0 Token Introspection Library Functions

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!NOTE] To view an example policy project that uses Omni Gateway Policy Development Kit (PDK)'s
> Token Introspection feature, see
> [OAuth 2.0 Token Introspection Policy Example](https://github.com/mulesoft/pdk-custom-policy-examples/blob/1.10.0/oauth-2-token-introspection/README.md).

Use the Omni Gateway Policy Development Kit (PDK) Token Introspection library functions to validate
incoming OAuth 2.0 tokens with an upstream introspection service.

## Configure the Token Validator

To access OAuth 2.0 Token Introspection functionality, you must import the `token_introspection`
module from the PDK crate and inject the `TokenValidatorBuilder` in the
[configure](https://docs.mulesoft.com/pdk/latest/policies-pdk-configure-features#policy-template) function.

```Rust
use pdk::token_introspection::{IntrospectionResult, ParsedToken, ScopesValidator, TokenValidator, TokenValidatorBuilder};

#[entrypoint]
async fn configure(
    launcher: Launcher,
    Configuration(bytes): Configuration,
    validator_builder: TokenValidatorBuilder,
) -> Result<()> {
// [...]
// Create a token validator
let mut validator_instance = validator_builder
        .new("token-cache")
        .with_path("/introspect")
        .with_authorization_value("Basic YWRtaW46YWRtaW4=") //  Choose either authorization value or client ID and secret depending on your service authorization. No authorization header is sent if with_authorization_value() isn't defined.
        .with_client_id("client-id") // Client ID and secret are sent as form params in the body of the request
        .with_client_secret("client-secret")
        .with_expires_in_attribute("exp")
        .with_max_token_ttl(600)
        .with_timeout_ms(10000)
        .with_max_cache_entries(10000)
        .with_scopes_validator(ScopesValidator::all(scopes_vector))
        .with_service(config.my_service)
        .with_protected_resource_metadata(config.auth_server_url) // Choose .with_protected_resource_metadata_with_properties() if additional properties are required

        .build();
// [...]
}
```

The `TokenValidatorBuilder` provides these methods to configure the token validator. You must call
`with_service` before `build`, all other methods are optional:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Method</th><th>Parameter</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>with_path</code></p></div></div></td><td><div><div><p>path (<code>impl Into&lt;String&gt;</code>)</p></div></div></td><td><div><div><p><code>"/"</code></p></div></div></td><td><div><div><p>Sets the introspection endpoint path.</p></div></div></td></tr><tr><td><div><div><p><code>with_authorization_value</code></p></div></div></td><td><div><div><p>value (<code>impl Into&lt;String&gt;</code>)</p></div></div></td><td><div><div><p><code>""</code> (Auth header with an empty value)</p></div></div></td><td><div><div><p>Sets the authorization header value for introspection requests.</p></div></div></td></tr><tr><td><div><div><p><code>with_client_id</code></p></div></div></td><td><div><div><p>value (<code>impl Into&lt;String&gt;</code>)</p></div></div></td><td><div><div><p>No default</p></div></div></td><td><div><div><p>Sets the client ID credential to talk with the introspection service.</p></div></div></td></tr><tr><td><div><div><p><code>with_client_secret</code></p></div></div></td><td><div><div><p>value (<code>impl Into&lt;String&gt;</code>)</p></div></div></td><td><div><div><p>No default</p></div></div></td><td><div><div><p>Sets the client secret credential to talk with the introspection service.</p></div></div></td></tr><tr><td><div><div><p><code>with_expires_in_attribute</code></p></div></div></td><td><div><div><p>attr (<code>impl Into&lt;String&gt;</code>)</p></div></div></td><td><div><div><p><code>"exp"</code></p></div></div></td><td><div><div><p>Sets the attribute name for expiration time in the introspection response.</p></div></div></td></tr><tr><td><div><div><p><code>with_max_token_ttl</code></p></div></div></td><td><div><div><p>ttl (<code>i64</code>)</p></div></div></td><td><div><div><p><code>-1</code> (no cap)</p></div></div></td><td><div><div><p>Sets the maximum token TTL in seconds; tokens with a longer TTL are treated as expired. Use <code>-1</code> for no limit.</p></div></div></td></tr><tr><td><div><div><p><code>with_timeout_ms</code></p></div></div></td><td><div><div><p>timeout (<code>u64</code>)</p></div></div></td><td><div><div><p><code>10000</code> (10 s)</p></div></div></td><td><div><div><p>Sets the timeout for introspection requests in milliseconds.</p></div></div></td></tr><tr><td><div><div><p><code>with_max_cache_entries</code></p></div></div></td><td><div><div><p>max_entries (<code>usize</code>)</p></div></div></td><td><div><div><p><code>1000</code></p></div></div></td><td><div><div><p>Sets the maximum number of entries in the token cache.</p></div></div></td></tr><tr><td><div><div><p><code>with_scopes_validator</code></p></div></div></td><td><div><div><p>validator (<code>ScopesValidator</code>)</p></div></div></td><td><div><div><p>No default</p></div></div></td><td><div><div><p>Sets the scopes validator for token validation (for example, <code>ScopesValidator::all(scopes_vector)</code>).</p></div></div></td></tr><tr><td><div><div><p><code>with_service</code></p></div></div></td><td><div><div><p>service (<code>Service</code>)</p></div></div></td><td><div><div><p>No default (required)</p></div></div></td><td><div><div><p>Sets the OAuth2 introspection service endpoint. Required to build the validator.</p></div></div></td></tr><tr><td><div><div><p><code>with_protected_resource_metadata</code></p></div></div></td><td><div><div><p>authorization server url (impl Into&lt;String&gt;)</p></div></div></td><td><div><div><p>No default</p></div></div></td><td><div><div><p>Enables RFC 9728 protected resource discovery with the given authorization server URL. The well-known endpoint path and resource URL are derived automatically from the API base path extracted from PDK metadata when the policy is applied.</p></div></div></td></tr><tr><td><div><div><p><code>with_protected_resource_metadata_with_properties</code></p></div></div></td><td><div><div><p>authorization server url (<code>impl Into&lt;String&gt;</code>), additional properties (Value)</p></div></div></td><td><div><div><p>No default</p></div></div></td><td><div><div><p>Enables RFC 9728 protected resource discovery with the given authorization server URL and additional metadata properties (such as <code>scopes_supported</code> or <code>bearer_methods_supported</code>). The well-known endpoint path and resource URL are derived automatically from the API base path extracted from PDK metadata when the policy is applied.</p></div></div></td></tr></tbody></table>

> [!NOTE] The configure function receives the
> [configuration parameters](https://docs.mulesoft.com/pdk/latest/policies-pdk-create-schema-definition) defined in your policy schema.

## Validate a Token

Once configured, the validator provides the `validate` function, that expects a token string. The
validate function sends a request to the introspection endpoint and returns the
`IntrospectionResult`:

```Rust
// extract token from header
let auth_header = handler.header("Authorization");
let token = auth_header.split_whitespace()[1];

let result = validator
        .validate(&token)
        .await
        .map_err(PolicyError::Introspection)?;
```

## See Also

- [Implementing Your Custom Policy Features in Rust](https://docs.mulesoft.com/pdk/latest/policies-pdk-configure-features)