---
schema_version: "1"
id: c8d7bbfe384ad83abb0338f9372af5399ff308d34787ff34610ab172df984d9f
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/1.7/policies-pdk-configure-features-token-introspection.md
canonical_url: https://docs.mulesoft.com/pdk/1.7/policies-pdk-configure-features-token-introspection
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 92c7faa19f8536ba73cd4b9551c0b2c79c4597993149ab621e5205d2197afb58
description: MuleSoft Documentation Site
release: "1.7"
latest: false
---
---
product: Omni Gateway Policy Development Kit (PDK)
version: 1.7
---

# 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 Flex 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.6.0/oauth-2-token-introspection/README.md).

Use the Flex 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/1.7/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=")
        .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)
        .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> (sends an 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_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>—</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>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></tbody></table>

> [!NOTE] The configure function receives the
> [configuration parameters](https://docs.mulesoft.com/pdk/1.7/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/1.7/policies-pdk-configure-features)