Skip to main content
POST
/
v1
/
sessions
Create Session
curl --request POST \
  --url https://api.truthlocks.com/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "scopes": [
    "datasets:read"
  ],
  "ttl_seconds": 1800
}
'
{
  "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "token": "<string>",
  "scopes": [
    "<string>"
  ],
  "status": "active",
  "metadata": {},
  "expires_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "terminated_at": "2023-11-07T05:31:56Z"
}

​
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.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
agent_id
string<uuid>
required

Agent to create the session for

​
scopes
string[]

Scopes for this session (must be subset of agent scopes)

​
ttl_seconds
integer
default:3600

Session time-to-live in seconds

Required range: 60 <= x <= 86400
​
metadata
object

Response

Session created

​
session_id
string<uuid>
​
agent_id
string<uuid>
​
token
string

Session bearer token (returned once on creation)

​
scopes
string[]
​
status
enum<string>
Available options:
active,
terminated,
expired
​
metadata
object
​
expires_at
string<date-time>
​
created_at
string<date-time>
​
terminated_at
string<date-time>