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

# Create a session

> Open a session for one logged-in customer, on the per-user door. Hand the `token` to the page's `init({ session })`, which expires 15 minutes later: see [Session renewal](/guides/session-renewal). Take the partition values from your own session, never from the request. On Node, call [`sessions.create`](/reference/node/sessions-create).



## OpenAPI

````yaml /openapi.yaml post /api/v1/embed/sessions
openapi: 3.1.0
info:
  title: Concatflow API
  version: '1'
  description: >-
    Server-to-server routes behind @concatflow/node. Call them from your backend
    only: the API key must never reach a browser.
servers:
  - url: https://app.concatflow.com
security:
  - apiKey: []
paths:
  /api/v1/embed/sessions:
    post:
      summary: Create a session
      description: >-
        Open a session for one logged-in customer, on the per-user door. Hand
        the `token` to the page's `init({ session })`, which expires 15 minutes
        later: see [Session renewal](/guides/session-renewal). Take the
        partition values from your own session, never from the request. On Node,
        call [`sessions.create`](/reference/node/sessions-create).
      operationId: createSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - assistant_id
                - partitions
              additionalProperties: false
              properties:
                assistant_id:
                  type: string
                  format: uuid
                  description: The assistant's ID.
                partitions:
                  type: object
                  minProperties: 1
                  description: >-
                    The customer, as `{ "key": "value" }`. Keys must be exactly
                    the partition keys of the assistant's isolation, at most 63
                    characters. Values are non-empty strings, at most 200
                    characters.
                  additionalProperties:
                    type: string
                    minLength: 1
                    maxLength: 200
            example:
              assistant_id: YOUR_ASSISTANT_ID
              partitions:
                customer_id: '4712'
      responses:
        '201':
          description: Session opened.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          $ref: '#/components/responses/InvalidBody'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '403':
          description: >-
            The partition keys differ from the assistant's isolation. `expected`
            lists them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartitionKeysMismatch'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            The assistant is not ready for the per-user door: `not_published`,
            `door_closed` or `isolation_unsigned`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantNotReady'
        '422':
          $ref: '#/components/responses/ValidationError'
        '502':
          $ref: '#/components/responses/BackendUnreachable'
components:
  schemas:
    Session:
      type: object
      required:
        - token
        - expires_at
      additionalProperties: false
      properties:
        token:
          type: string
          description: Opaque session token, for this customer on this assistant.
        expires_at:
          type: string
          format: date-time
          description: 15 minutes after the session was opened.
      example:
        token: Qm8x…
        expires_at: '2026-10-23T14:37:12.204000+00:00'
    PartitionKeysMismatch:
      type: object
      required:
        - detail
      properties:
        detail:
          type: object
          required:
            - code
            - expected
          properties:
            code:
              const: partition_keys_mismatch
            expected:
              type: array
              items:
                type: string
      example:
        detail:
          code: partition_keys_mismatch
          expected:
            - customer_id
    AssistantNotReady:
      type: object
      required:
        - detail
      properties:
        detail:
          type: object
          required:
            - code
          properties:
            code:
              enum:
                - not_published
                - door_closed
                - isolation_unsigned
      example:
        detail:
          code: door_closed
    RelayError:
      type: object
      required:
        - error
      additionalProperties: false
      properties:
        error:
          type: string
  responses:
    InvalidBody:
      description: Malformed body, an ID that is not a UUID, or no `partition`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RelayError'
          example:
            error: invalid_body
    InvalidApiKey:
      description: Missing, wrong or revoked API key. Checked first.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RelayError'
          example:
            error: invalid_api_key
    NotFound:
      description: Unknown assistant, or one from another workspace.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail: {}
    ValidationError:
      description: A partition key over 63 characters, or a value over 200.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: array
    BackendUnreachable:
      description: Concatflow could not reach its API. Retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RelayError'
          example:
            error: backend_unreachable
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Your secret API key, `lyra_sk_…`, from **Settings → Developers → API
        keys**.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.