Create Session
Agent Sessions & Tools
Create Session
Create a time-bound authenticated session for a machine agent with scoped access tokens
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.
Authentication
RequiresX-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
Authorizations
API key for machine-to-machine authentication
Body
application/json
Response
Session created

