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

# Create a session

> Creates a new partial-import session and mints the initial hydration token to pass to the widget. Requires your **backend** license key — never call this client-side.



## OpenAPI

````yaml /api-reference/sessions-openapi.json post /auth/
openapi: 3.1.0
info:
  title: Dromo Sessions API
  description: APIs for managing partial-import save/restore sessions.
  version: '1.0'
servers:
  - url: https://app.dromo.io/api/widget/session/v2
security:
  - backend_license_key: []
tags:
  - name: sessions
    description: Managing partial-import save/restore sessions
paths:
  /auth/:
    post:
      tags:
        - sessions
      summary: Create a session
      description: >-
        Creates a new partial-import session and mints the initial hydration
        token to pass to the widget. Requires your **backend** license key —
        never call this client-side.
      operationId: createSession
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreate'
      responses:
        '201':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionCreated'
components:
  schemas:
    SessionCreate:
      type: object
      properties:
        import_identifier:
          type: string
          example: user_import_v1
          description: >-
            A label for your own bookkeeping (e.g. schema name, import type).
            Not used for lookups. Defaults to "".
        expires_in:
          type: integer
          example: 3600
          description: Hydration token TTL in seconds. Defaults to 21600 (6 hours).
    SessionCreated:
      type: object
      properties:
        sessionId:
          type: string
          format: uuid
          example: 1b6acf28-8748-4120-8d7a-4b7846d5e487
          description: >-
            Backend session identifier. Persist this durably — needed to resume
            the session or delete it later.
        hydrationId:
          type: string
          example: <signed-token>
          description: >-
            Short-lived access token. Pass this to the widget to start or resume
            the session.
        expiresIn:
          type: integer
          example: 21600
          description: Seconds until the hydrationId expires.
        savedAt:
          type: string
          format: date-time
          example: '2026-06-19T18:00:00.000Z'
  securitySchemes:
    backend_license_key:
      type: apiKey
      name: X-DROMO-LICENSE-KEY
      in: header
      description: >-
        Your **backend** license key (`is_for_backend_api=True`) from the [Dromo
        Dashboard](https://dashboard.dromo.io/). Never expose this client-side.

````