Create Session

Create a time-bound authenticated session for a machine agent with scoped access tokens

Create Session

POST /v1/agent-sessions

Creates a new authenticated session for a machine agent. The session binds a time-limited access token and refresh token to the agent, with an explicit scope set that must be a subset of the agent’s granted scopes.

The token and refresh_token are returned only in the creation response. Store them securely — they cannot be retrieved later.

The token and refresh_token fields are only returned once in this response. Store them in a secure secrets manager or encrypted storage immediately. If lost, terminate the session and create a new one.

Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

Request Body

agent_id · string · required

The MAIP agent identifier for which to create the session (e.g., maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH). The agent must exist and be in "active" status.

scopes · string[]

Scopes for this session. Must be a subset of the agent’s assigned scopes (scope narrowing). If omitted, inherits all of the agent’s scopes.

ttl_minutes · integer

Session lifetime in minutes. Range: 1 to 1440 (24 hours). Default: 60 (1 hour). Sessions cannot exceed the 24-hour maximum TTL.

metadata · object

Arbitrary session metadata. Useful for tracking purpose, environment, or orchestration context.

Response

session · object

The created session object containing:

session.id · string

Internal UUID primary key.

session.session_id · string

MAIP session identifier in format maip-sess:<short-uuid>:<random-hex>. Use this ID in subsequent API calls.

session.agent_id · string

The agent this session belongs to.

session.status · string

Session status. Always "active" on creation.

session.scopes · string[]

The effective scopes for this session.

session.metadata · object

Session metadata.

session.expires_at · string

ISO 8601 expiration timestamp.

session.created_at · string

ISO 8601 creation timestamp.

session.updated_at · string

ISO 8601 last-updated timestamp.

token · string

Opaque access token for authenticating API requests within this session. 64-character hex string. Returned only once.

refresh_token · string

Token for refreshing the session before expiry. 64-character hex string. Returned only once.

Example

curl -X POST https://api.truthlocks.com/v1/agent-sessions \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH",
    "scopes": ["data:read", "tool:search.web"],
    "ttl_minutes": 120,
    "metadata": {
      "purpose": "customer-inquiry-batch-2026-04-06",
      "orchestrator": "support-pipeline-v2"
    }
  }'

---

Session Lifecycle

Created (active) --> Refreshed (active) --> Expired (expired)
      |                                         |
      +--> Terminated (terminated)               |
      |                                         |
      +--> Handed Off (handed_off) --> New Session (active)

A session receipt is automatically created when the session starts, linking the session to the agent’s audit trail.