openapi: 3.0.0
info:
  title: GarminSync Authentication API with MFA
  version: 1.0.0
  description: API for authenticating users with MFA support using garth
paths:
  /api/garmin/login:
    post:
      summary: Authenticate user with optional MFA
      description: Authenticate a user with username and password, with support for MFA challenges
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: User's Garmin Connect username or email
                password:
                  type: string
                  description: User's Garmin Connect password
                mfa_code:
                  type: string
                  description: MFA code if authentication requires it
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  session_id:
                    type: string
                    description: Unique identifier for the authenticated session
                  access_token:
                    type: string
                    description: Access token for API calls
                  token_type:
                    type: string
                    description: Type of token (e.g., Bearer)
                  expires_in:
                    type: integer
                    description: Time until token expiration in seconds
                  mfa_required:
                    type: boolean
                    description: Whether MFA is required for this account
                  mfa_challenge_id:
                    type: string
                    description: ID for MFA challenge if MFA is required (available in initial response)
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                        description: User identifier
                      email:
                        type: string
                        description: User's email address
        '400':
          description: Invalid credentials or MFA code
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    description: Error message
                  mfa_required:
                    type: boolean
                    description: Whether MFA is required
                  mfa_challenge_id:
                    type: string
                    description: ID for the MFA challenge
                  mfa_type:
                    type: string
                    description: Type of MFA challenge (push, sms, email)
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    description: Error message
        '429':
          description: Too many failed authentication attempts
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    description: Error message
                  retry_after:
                    type: integer
                    description: Seconds to wait before retrying