> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devctrl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Sessions

> Create scoped, time-limited tokens that bind an agent to a specific task with context.

Task sessions are short-lived tokens that connect an agent's identity to a specific task. They carry context (like a customer ID or ticket number) that policies can reference to scope access.

## Create a task session

```bash theme={null}
curl -X POST https://gateway.devctrl.ai/v1/tasks/sessions \
  -H "Authorization: Bearer YOUR_CREDENTIAL_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "task_abc123",
    "context": {
      "ticket_id": "TICKET-123",
      "customer_id": "cust_456"
    },
    "ttl": 3600
  }'
```

**Request body:**

| Field     | Type    | Required | Description                                                                   |
| --------- | ------- | -------- | ----------------------------------------------------------------------------- |
| `taskId`  | string  | Yes      | The task definition ID from the console                                       |
| `context` | object  | Yes      | Runtime context for this task instance. Must match the task's context schema. |
| `ttl`     | integer | No       | Time-to-live in seconds. Default: 3600 (1 hour). Max: 86400 (24 hours).       |

**Response:**

```json theme={null}
{
  "taskToken": "a1b2c3d4e5f6g7h8...",
  "tokenId": "ts_abc123",
  "expiresAt": "2026-04-10T15:00:00Z"
}
```

## Use a task session

Include the task token in subsequent MCP requests using the `X-Task-Token` header alongside your `Authorization` header:

```
Authorization: Bearer YOUR_CREDENTIAL_SECRET
X-Task-Token: a1b2c3d4e5f6g7h8...
```

In the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), add both headers before connecting. MCP clients and SDKs include these headers in the transport configuration.

The gateway resolves the task session and makes the task context available during policy evaluation.

## Get the current session

```bash theme={null}
curl https://gateway.devctrl.ai/v1/tasks/sessions/current \
  -H "Authorization: Bearer YOUR_CREDENTIAL_SECRET" \
  -H "X-Task-Token: a1b2c3d4e5f6g7h8..."
```

Returns the active session details including the task name, context, and expiry time.

## Delete a session

End a task session early when the agent finishes its work:

```bash theme={null}
curl -X DELETE https://gateway.devctrl.ai/v1/tasks/sessions/current \
  -H "Authorization: Bearer YOUR_CREDENTIAL_SECRET" \
  -H "X-Task-Token: a1b2c3d4e5f6g7h8..."
```

This immediately invalidates the task token. Any subsequent requests using it will be rejected.

<Tip>
  Always delete task sessions when the agent finishes a task. This follows the principle of least privilege — don't keep access open longer than needed.
</Tip>

## Lifecycle

```
Create session          Use session              Session ends
     │                       │                        │
     ▼                       ▼                        ▼
POST /v1/tasks/sessions → X-Task-Token header → TTL expires
     │                       │                   or DELETE
     │                       │                        │
     └── Context validated   └── Policies check       └── Token invalidated
         against schema          task.context
```

## Context validation

When you create a task session, the gateway validates the `context` field against the task's JSON Schema. If the context doesn't match, the session is rejected with a `400` error.

```json theme={null}
// Task schema requires ticket_id (string) and customer_id (string)
// This context is valid:
{ "ticket_id": "TICKET-123", "customer_id": "cust_456" }

// This context is invalid (missing required field):
{ "ticket_id": "TICKET-123" }
// → 400 Bad Request: context validation failed
```

## Notes

* An agent can have multiple active task sessions simultaneously
* Task sessions are tied to both the identity and the task definition
* The maximum TTL is 24 hours to prevent long-lived access tokens
* Both the bearer token and task token must be valid for a request to succeed