openapi: 3.1.0
info:
  title: Quub Exchange - Authentication Service
  version: 2.0.0
  description: |
    Authentication and session management service.

    Handles user authentication, registration, password management, and session lifecycle.

servers:
  - url: https://api.quub.exchange/v2
    description: Production API
  - url: https://api.sandbox.quub.exchange/v2
    description: Sandbox API

tags:
  - name: Authentication
    description: Login, logout, and session management operations.
  - name: Registration
    description: User registration and account creation.
  - name: Password
    description: Password management operations.

paths:
  /auth/login:
    post:
      tags:
        - Authentication
      summary: Login with email and password
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        "200":
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/AuthSession"
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError

  /auth/logout:
    post:
      tags:
        - Authentication
      summary: Logout current session
      operationId: logout
      security:
        - oauth2: []
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sessionId:
                  type: string
                  format: uuid
      responses:
        "200":
          description: Logout successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError

  /auth/register:
    post:
      tags:
        - Registration
      summary: Register new user account
      operationId: register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
                firstName:
                  type: string
                lastName:
                  type: string
      responses:
        "201":
          description: Registration successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/AuthSession"
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "409":
          $ref: ./common/responses.yaml#/components/responses/Conflict
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError

  /auth/me:
    get:
      tags:
        - Authentication
      summary: Get current authenticated user
      operationId: getCurrentUser
      security:
        - oauth2: []
        - apiKey: []
      responses:
        "200":
          description: Current user retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: ./common/domain-models.yaml#/components/schemas/Account
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "404":
          $ref: ./common/responses.yaml#/components/responses/NotFound
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError

  /auth/password/change:
    post:
      tags:
        - Password
      summary: Change account password
      operationId: changePassword
      security:
        - oauth2: []
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - currentPassword
                - newPassword
              properties:
                currentPassword:
                  type: string
                  format: password
                newPassword:
                  type: string
                  format: password
      responses:
        "200":
          description: Password changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
        "400":
          $ref: ./common/responses.yaml#/components/responses/BadRequest
        "401":
          $ref: ./common/responses.yaml#/components/responses/Unauthorized
        "404":
          $ref: ./common/responses.yaml#/components/responses/NotFound
        "500":
          $ref: ./common/responses.yaml#/components/responses/InternalServerError

components:
  securitySchemes:
    oauth2:
      $ref: ./common/components.yaml#/components/securitySchemes/oauth2
    apiKey:
      $ref: ./common/components.yaml#/components/securitySchemes/apiKey

  schemas:
    AuthSession:
      type: object
      description: Authentication session information
      properties:
        account:
          $ref: ./common/domain-models.yaml#/components/schemas/Account
        token:
          type: string
          description: JWT access token
        refreshToken:
          type: string
          description: JWT refresh token
        expiresAt:
          type: string
          format: date-time
          description: Token expiration timestamp