---
title: token_cache
sidebarTitle: token_cache
---

# `fastmcp.utilities.token_cache`


In-memory cache for token verification results.

Provides a generic TTL-based cache for ``AccessToken`` objects, designed to
reduce repeated network calls during opaque-token verification.  Only
*successful* verifications should be cached; errors and failures must be
retried on every request.

Example:
    ```python
    from fastmcp.utilities.token_cache import TokenCache

    cache = TokenCache(ttl_seconds=300, max_size=10000)

    # On cache miss, call the upstream verifier and store the result.
    hit, token = cache.get(raw_token)
    if not hit:
        token = await _call_upstream(raw_token)
        if token is not None:
            cache.set(raw_token, token)
    ```


## Classes

### `TokenCache` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/token_cache.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


TTL-based in-memory cache for ``AccessToken`` objects.

Features:
- SHA-256 hashed cache keys (fixed size, regardless of token length).
- Per-entry TTL that respects both the configured ``ttl_seconds`` and the
  token's own ``expires_at`` claim (whichever is sooner).
- Bounded size with FIFO eviction when the cache is full.
- Periodic cleanup of expired entries to prevent unbounded growth.
- Defensive deep copies on both store and retrieve to prevent
  callers from mutating cached values.

Caching is disabled when ``ttl_seconds`` is ``None`` or ``0``, or
when ``max_size`` is ``0``.  Negative values raise ``ValueError``.


**Methods:**

#### `enabled` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/token_cache.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
enabled(self) -> bool
```

Return whether caching is active.


#### `get` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/token_cache.py#L95" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, token: str) -> tuple[bool, AccessToken | None]
```

Look up a cached verification result.

**Returns:**
- ``(True, AccessToken)`` on a cache hit, ``(False, None)`` on a miss
- or when caching is disabled.  The returned ``AccessToken`` is a deep
- copy that is safe to mutate.


#### `set` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/token_cache.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(self, token: str, result: AccessToken) -> None
```

Store a *successful* verification result.

Only successful verifications should be cached.  Failures (inactive
tokens, missing scopes, HTTP errors, timeouts) must **not** be cached
so that transient problems do not produce sticky false negatives.

