Task Sessions

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

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:

{
  "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, 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

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:

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.

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.

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.

// 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

Get Started

Core Concepts

Console Guide

Gateway

Policies

Create a task session

Use a task session

Get the current session

Delete a session

Lifecycle

Context validation

Notes

​Create a task session

​Use a task session

​Get the current session

​Delete a session

​Lifecycle

​Context validation

​Notes

Create a task session

Use a task session

Get the current session

Delete a session

Lifecycle

Context validation

Notes