Sessions

A session is a short-lived, revocable credential that lets an MCP client connect as a single tenant user. Instead of handing an agent your workspace API key, you mint a session: it returns an MCP URL plus a bearer token (an nv_sess_… token) that expires and can be revoked at any time. The session’s tool list is the fused native + third-party toolset, filtered by that user’s Account Kit. See Architecture → Sessions.

Tools

Tool	Type	Description
`sessions_create`	Core	Mint a TTL-limited MCP session for a user
`sessions_list`	Core	List a user’s sessions and their status
`sessions_revoke`	Management	Revoke a session immediately

Creating a Session

The token travels in the Authorization header — never in the URL. The returned mcp.url + mcp.headers are everything an MCP client needs to connect.

curl -X POST https://api.usenaive.ai/v1/users/{user_id}/sessions \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "ttl_ms": 900000 }'

// Scoped to a specific user…
const session = await naive.forUser(alice.id).sessions.create({ ttlMs: 15 * 60 * 1000 });
// …or the default user (sugar):
const s = await naive.session();

// session.mcp.url + session.mcp.headers → hand to your MCP client

Response:

{
  "id": "8db5b930-12cb-4563-8e40-5aebb100f28f",
  "expires_at": "2026-06-04T07:05:07Z",
  "mcp": {
    "url": "https://api.usenaive.ai/mcp/sse/8db5b930-12cb-4563-8e40-5aebb100f28f",
    "headers": { "Authorization": "Bearer nv_sess_…" },
    "expires_at": "2026-06-04T07:05:07Z"
  }
}

Parameters

Param	Type	Required	Default	Description
`ttl_ms`	number	No	900000 (15 min)	Session lifetime in ms (max 24h)

The MCP connection is bound to the session’s tenant user: multi-tenant tools (connections, vault, logs) default to that user, and execution stays gated by the user’s Account Kit. Revoke a session and the connection is rejected immediately.

Listing & Revoking

# List a user's sessions (tokens are never returned)
curl https://api.usenaive.ai/v1/users/{user_id}/sessions \
  -H "Authorization: Bearer nv_sk_your_key"

# Revoke immediately
curl -X DELETE https://api.usenaive.ai/v1/users/{user_id}/sessions/{session_id} \
  -H "Authorization: Bearer nv_sk_your_key"

A session is active, expired (past its TTL), or revoked.

Error Handling

Error	Cause	Recovery
`not_found`	Invalid `session_id` / `user_id`	Use `GET .../sessions` for valid ids
`unauthorized`	The `nv_sess_…` token is expired or revoked (at connect time)	Mint a fresh session
`invalid_input`	`ttl_ms` out of range	Use 1ms–24h

Typical Workflow

Give a user's agent scoped MCP access without sharing your key
    │
    ├─ POST /v1/users/alice/sessions          → mint session
    │   { ttl_ms: 900000 }
    │   → mcp.url + Authorization: Bearer nv_sess_…
    │
    ├─ MCP client connects to mcp.url with the bearer header
    │   → tools fused (native + connections), gated by Alice's Account Kit
    │
    └─ DELETE /v1/users/alice/sessions/{id}    → revoke when done (connection drops)

Getting Started

Agent Profiles

Architecture

Primitives

Tools

Creating a Session

Parameters

Listing & Revoking

Error Handling

Typical Workflow

​Tools

​Creating a Session

​Parameters

​Listing & Revoking

​Error Handling

​Typical Workflow

Tools

Creating a Session

Parameters

Listing & Revoking

Error Handling

Typical Workflow