> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
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 for this session. Must be a subset of the agent's assigned scopes
(scope narrowing). If omitted, inherits all of the agent's scopes.
Session lifetime in minutes. Range: 1 to 1440 (24 hours). Default: `60` (1
hour). Sessions cannot exceed the 24-hour maximum TTL.
Arbitrary session metadata. Useful for tracking purpose, environment, or
orchestration context.
### Response
The created session object containing:
Internal UUID primary key.
MAIP session identifier in format `maip-sess::`.
Use this ID in subsequent API calls.
The agent this session belongs to.
Session status. Always `"active"` on creation.
The effective scopes for this session.
Session metadata.
ISO 8601 expiration timestamp.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
Opaque access token for authenticating API requests within this session.
64-character hex string. **Returned only once.**
Token for refreshing the session before expiry. 64-character hex string.
**Returned only once.**
### Example
```bash theme={null}
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.
## OpenAPI
````yaml mint-openapi.yaml POST /v1/agent-sessions
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/agent-sessions:
post:
tags:
- Machine Identity
summary: Create Session
description: >
Creates a short-lived session for an agent. The session token is
returned once
and must be used in subsequent requests within the TTL window.
operationId: maip.sessions.create
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- agent_id
properties:
agent_id:
type: string
format: uuid
description: Agent to create the session for
scopes:
type: array
items:
type: string
description: Scopes for this session (must be subset of agent scopes)
ttl_seconds:
type: integer
minimum: 60
maximum: 86400
default: 3600
description: Session time-to-live in seconds
metadata:
type: object
additionalProperties: true
example:
agent_id: 550e8400-e29b-41d4-a716-446655440000
scopes:
- datasets:read
ttl_seconds: 1800
responses:
'201':
description: Session created
content:
application/json:
schema:
$ref: '#/components/schemas/MaipSession'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- APIKey: []
components:
schemas:
MaipSession:
type: object
properties:
session_id:
type: string
format: uuid
agent_id:
type: string
format: uuid
token:
type: string
description: Session bearer token (returned once on creation)
scopes:
type: array
items:
type: string
status:
type: string
enum:
- active
- terminated
- expired
metadata:
type: object
additionalProperties: true
expires_at:
type: string
format: date-time
created_at:
type: string
format: date-time
terminated_at:
type: string
format: date-time
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````