Skip to main content
POST
Create Session

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

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.
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.
integer
Session lifetime in minutes. Range: 1 to 1440 (24 hours). Default: 60 (1 hour). Sessions cannot exceed the 24-hour maximum TTL.
object
Arbitrary session metadata. Useful for tracking purpose, environment, or orchestration context.

Response

object
The created session object containing:
string
Internal UUID primary key.
string
MAIP session identifier in format maip-sess:<short-uuid>:<random-hex>. Use this ID in subsequent API calls.
string
The agent this session belongs to.
string
Session status. Always "active" on creation.
string[]
The effective scopes for this session.
object
Session metadata.
string
ISO 8601 expiration timestamp.
string
ISO 8601 creation timestamp.
string
ISO 8601 last-updated timestamp.
string
Opaque access token for authenticating API requests within this session. 64-character hex string. Returned only once.
string
Token for refreshing the session before expiry. 64-character hex string. Returned only once.

Example


Session Lifecycle

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>