> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sidenet.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mint session token

> Exchanges your organization API key for a short-lived access token scoped to one end user, safe to hand to a browser.

Call this from your backend only — it takes the user id, optionally the group id, and optionally the user's tool credentials. An omitted `group_id` falls back to the user's current group, then the organization's Default group. Display names live on the update routes (`PATCH /v1/users/{userId}` / `PATCH /v1/groups/{groupId}`), not here.

Session tokens are scoped to the chat runtime. Endpoints that modify your organization — agents, workflows, prompt blocks, tool providers — require the API key from your backend.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/token
openapi: 3.1.0
info:
  title: Sidenet API
  version: 1.0.0
  description: >-
    Sidenet HTTP endpoints exposed by the Sidenet Studio. All routes require an
    api key that can be generated through the studio in studio.sidenet.ai.
servers:
  - url: https://api.sidenet.ai
security:
  - bearerAuth: []
paths:
  /v1/token:
    post:
      tags:
        - Authentication
      summary: Mint session token
      description: >-
        Exchanges your organization API key for a short-lived access token
        scoped to one end user, safe to hand to a browser.


        Call this from your backend only — it takes the user id, optionally the
        group id, and optionally the user's tool credentials. An omitted
        `group_id` falls back to the user's current group, then the
        organization's Default group. Display names live on the update routes
        (`PATCH /v1/users/{userId}` / `PATCH /v1/groups/{groupId}`), not here.


        Session tokens are scoped to the chat runtime. Endpoints that modify
        your organization — agents, workflows, prompt blocks, tool providers —
        require the API key from your backend.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
              properties:
                user_id:
                  type: string
                  example: user_4821
                  description: >-
                    Your stable id for the end user. Becomes their identity on
                    every call this token makes. An id that hasn't been seen
                    before CREATES the user — name them via `PATCH
                    /v1/users/{userId}`, or pre-create with POST /v1/users.
                group_id:
                  type: string
                  example: grp_84f20c19
                  description: >-
                    The group this session belongs to — today the unit billing
                    and spend caps attach to. An id that hasn't been seen before
                    CREATES the group, with the default spend cap — name and cap
                    it via `PATCH /v1/groups/{groupId}`, or pre-create with POST
                    /v1/groups. Optional: when omitted, the session uses the
                    user's current group (set by a previous mint, chat call, or
                    `PATCH /v1/users/{userId}`), falling back to the
                    organization's Default group. Send it explicitly if you bill
                    per team — the fallback is silent.
                tools_auth:
                  type: object
                  example:
                    8d3b1a75-6c02-4e59-b84f-27a9d5e10c63:
                      credentials:
                        token: the end user's CRM token
                  description: >-
                    Per-provider credentials, keyed by tool provider id — `{
                    "PROVIDER_ID": { "credentials": { … }, "base_url"?: "…" }
                    }`. Stored on the user (encrypted at rest) and injected
                    server-side on every call they make — sessions, workflow
                    runs and schedules alike. Only the providers you send are
                    replaced. Never returned, logged, or cached.
      responses:
        '200':
          description: Session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: Bearer token for the chat runtime. Prefixed `snat_`.
                  refresh_token:
                    type: string
                    description: >-
                      Single-use token for POST /v1/token/refresh. Prefixed
                      `snrt_`.
                  token_type:
                    type: string
                    example: Bearer
                  expires_in:
                    type: number
                    description: Access token lifetime in seconds.
                  refresh_expires_in:
                    type: number
                    description: Refresh token lifetime in seconds.
        '400':
          description: Missing or invalid user_id, or invalid group / provider credentials
        '401':
          description: Missing or invalid organization API key
        '403':
          description: Caller is not an organization API key
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Organization API key, generated in studio.sidenet.ai. Backend only —
        never in a browser.

````