---
title: keys
sidebarTitle: keys
---

# `fastmcp.server.tasks.keys`


Docket and Redis key encoding for background tasks.

The compound Docket task key embeds the auth boundary so that the parser can
reject cross-scope access without consulting Redis.  Authenticated and
anonymous tasks live in disjoint keyspaces:

    auth:{enc_scope}:{client_task_id}:{task_type}:{enc_identifier}
    anon:{client_task_id}:{task_type}:{enc_identifier}

The same `auth/anon` partition is used for the per-task Redis prefix
(``fastmcp:task:auth:{enc_scope}`` vs ``fastmcp:task:anon``) — see
``task_redis_prefix``.

``task_scope`` is the raw scope identifier (typically derived from
``client_id`` or ``client_id|sub``); encoding happens once, at the boundary,
in this module.


## Functions

### `build_task_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_task_key(task_scope: str | None, client_task_id: str, task_type: str, component_identifier: str) -> str
```


Build Docket task key with embedded metadata.

When ``task_scope`` is ``None`` the task is anonymous and lives in the
``anon`` keyspace.  Otherwise it lives under ``auth:{enc_scope}``.

**Args:**
- `task_scope`: Raw authorization scope, or ``None`` for anonymous tasks
- `client_task_id`: Client-provided task ID
- `task_type`: Type of task ("tool", "prompt", "resource")
- `component_identifier`: Tool name, prompt name, or resource URI

**Returns:**
- Encoded task key for Docket

**Examples:**

>>> build_task_key("client-a", "task456", "tool", "my_tool")
'auth:client-a:task456:tool:my_tool'
>>> build_task_key(None, "task456", "tool", "my_tool")
'anon:task456:tool:my_tool'
>>> build_task_key("client-a", "task456", "resource", "file://data.txt")
'auth:client-a:task456:resource:file%3A%2F%2Fdata.txt'


### `parse_task_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L80" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parse_task_key(task_key: str) -> TaskKeyParts
```


Parse Docket task key to extract metadata.

**Args:**
- `task_key`: Encoded task key from Docket

**Returns:**
- Dict with keys: ``task_scope`` (``str | None``), ``client_task_id``,
- ``task_type``, ``component_identifier``.

**Raises:**
- `ValueError`: If the key has an unrecognized tag or wrong segment count.

**Examples:**

>>> parse_task_key("auth:client-a:task456:tool:my_tool")
`{'task_scope': 'client-a', 'client_task_id': 'task456', 'task_type': 'tool', 'component_identifier': 'my_tool'}`
>>> parse_task_key("anon:task456:tool:my_tool")
`{'task_scope': None, 'client_task_id': 'task456', 'task_type': 'tool', 'component_identifier': 'my_tool'}`


### `get_client_task_id_from_key` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_client_task_id_from_key(task_key: str) -> str
```


Extract just the client task ID from a task key.

**Args:**
- `task_key`: Full encoded task key

**Returns:**
- Client-provided task ID

**Examples:**

>>> get_client_task_id_from_key("auth:client-a:task456:tool:my_tool")
'task456'
>>> get_client_task_id_from_key("anon:task456:tool:my_tool")
'task456'


### `task_redis_prefix` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L156" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
task_redis_prefix(task_scope: str | None) -> str
```


Return the Redis key prefix that owns a given scope.

Authenticated tasks live under ``fastmcp:task:auth:{enc_scope}``;
anonymous tasks live under ``fastmcp:task:anon``.  Callers append
``f":{task_id}:..."`` to compose the final key.


## Classes

### `TaskKeyParts` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/keys.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Decoded segments of a Docket task key.

``task_scope`` is ``None`` for anonymous tasks, the raw scope string
otherwise.

