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

# Sign in

> Exchanges a signed sign-in message for a session token.



## OpenAPI

````yaml gateway-openapi.yaml POST /v1/session
openapi: 3.1.0
info:
  contact: {}
  description: HTTP entry point to the Molpha oracle protocol.
  title: Molpha Gateway API
  version: '1.0'
  x-mint:
    metadata:
      description: >-
        Dispatch oracle rounds, collect threshold signatures, and return
        payloads for Solana, EVM, and Starknet verification.
servers:
  - url: https://gateway.molpha.io
    description: Devnet (SDK default)
security: []
tags:
  - name: health
    x-group: Health
    description: Liveness probes
  - name: gateway
    x-group: Gateway
    description: Gateway identity and the RequestAuth window
  - name: nodes
    x-group: Nodes
    description: Oracle node discovery
  - name: providers
    x-group: Providers
    description: Integrated data providers
  - name: round
    x-group: Subscription rounds
    description: Subscription and delegate execute path
  - name: session
    x-group: Sessions
    description: >-
      Sign-In-With-X sessions (served when `GET /v1/info` reports `sessionAuth`
      true)
  - name: x402
    x-group: x402 pay-per-request
    description: >-
      Pay-per-request path paid in USDC to the protocol treasury (requires a
      configured facilitator)
paths:
  /v1/session:
    post:
      tags:
        - session
      summary: Sign in
      description: Exchanges a signed sign-in message for a session token.
      parameters:
        - name: SIGN-IN-WITH-X
          in: header
          required: true
          description: Base64 JSON sign-in payload
          schema:
            type: string
      requestBody:
        required: false
        description: Optional shorter lifetime
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionSignInRequest'
      responses:
        '201':
          description: Session opened
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '400':
          description: >-
            Missing or malformed `SIGN-IN-WITH-X` header, or `ttlSeconds` out of
            range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >-
            The message is not this gateway's, has expired, was already used, or
            its signature does not verify
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            The signer has no active subscription or delegate account under the
            named owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Sessions are not enabled on this gateway
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Transient chain-read or storage failure, or too many sign-ins in
            progress. Retry after the `Retry-After` header with the same
            message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SessionSignInRequest:
      type: object
      description: Optional body of `POST /v1/session`.
      properties:
        ttlSeconds:
          type: integer
          description: >-
            Asks for a shorter session than the default; at most
            `sessionMaxTtlSeconds` from `GET /v1/info`. Omit it for the default
            lifetime.
          example: 900
    SessionResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        data:
          $ref: '#/components/schemas/SessionData'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: validation failed
    SessionData:
      type: object
      description: A new session. The token is returned once and is not recoverable.
      properties:
        token:
          type: string
          description: 'Sent as `Authorization: Bearer <token>` on `POST /v1/round/execute`.'
          example: molpha_sess_2tq1m0Yk3fJmJ1m9c0vX8q7Wb5sZr4nH6uL2pD9aE0g
        tokenType:
          type: string
          example: Bearer
        sessionId:
          type: string
          description: >-
            Identifies the session in the gateway's records; it is not a
            credential.
          example: 9f2c4e6a8b0d1f3a5c7e9b1d3f5a7c9e
        authority:
          type: string
          description: The key that signed in.
          example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
        owner:
          type: string
          description: The subscription owner the session acts under.
          example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
        role:
          type: string
          description: '`owner` or `delegate`.'
          example: delegate
        gatewayPda:
          type: string
          example: 4Nd1mYQzS5mQd9a8o3Yw2fGzLZk1h9dJ7R2sZb6xT3Vk
        programId:
          type: string
          example: MoLPhaXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX
        issuedAt:
          type: integer
          description: Unix seconds.
          example: 1791374400
        expiresAt:
          type: integer
          description: Unix seconds.
          example: 1791376200

````

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