Skip to main content
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:
FieldTypeRequiredDescription
taskIdstringYesThe task definition ID from the console
contextobjectYesRuntime context for this task instance. Must match the task’s context schema.
ttlintegerNoTime-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