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.
| 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 }'
{
"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"
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)
