SparkyFitness Authentication API

openapi: 3.2.0
info:
  title: SparkyFitness Authentication API
  version: 1.0.0
  description: API documentation for the SparkyFitness application, providing a comprehensive guide to all available endpoints. Have caution using the API directly, as improper use may lead to data loss or corruption.  Also note that the API is subject to change without notice due to heavy development, so always refer to the latest documentation for up-to-date information. It might have flaw and due to vite/nginx internal proxy actual end point accessed via front end URL might be different than hitting them directly on the server.
  contact:
    name: SparkyFitness Support
servers:
- url: https://{host}/api
  description: Self-hosted SparkyFitness instance (the operator supplies the host). The upstream spec declares the relative base "/api".
  variables:
    host:
      default: sparkyfitness.example.com
      description: Hostname of your own SparkyFitness deployment. SparkyFitness is self-hosted; there is no vendor-operated API host.
security:
- apiKeyAuth: []
tags:
- name: Authentication
paths:
  /auth/settings:
    get:
      summary: Get public authentication settings and available OIDC providers
      tags:
      - Authentication
      responses:
        '200':
          description: Login settings and OIDC providers
  /auth/mfa-factors:
    get:
      summary: Get enabled MFA factors for a user by email
      tags:
      - Authentication
      parameters:
      - in: query
        name: email
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Enabled MFA factors
        '400':
          description: Email is required
  /auth/web-login/register-ticket:
    post:
      summary: Mint a single-use, short-lived passkey registration ticket
      description: 'Authenticated with the caller''s Bearer session token. Requires a fresh session (recent login); returns 403 SESSION_NOT_FRESH otherwise so the client can re-authenticate. The returned ticket is handed to the browser registration page so the raw session token never appears in a URL.

        '
      tags:
      - Authentication
      responses:
        '200':
          description: Ticket minted
        '401':
          description: Missing or invalid session
        '403':
          description: Session not fresh; re-authentication required
  /auth/web-login/redeem-ticket:
    post:
      summary: Redeem a single-use passkey registration ticket
      description: 'Public (the ticket is the credential) and rate-limited. Returns the session token in the JSON body exactly once; the ticket is then consumed.

        '
      tags:
      - Authentication
      responses:
        '200':
          description: Session token returned
        '400':
          description: Invalid, used, or expired ticket
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key authentication via x-api-key header.
x-provenance:
  generated: '2026-08-27'
  method: derived
  source: https://github.com/CodeWithCJ/SparkyFitness — assembled from the project's own swagger-jsdoc configuration (SparkyFitnessServer/config/swagger.ts) and the 419 @swagger JSDoc blocks in SparkyFitnessServer/routes/**, using the same scan paths and the same cookieAuth->apiKeyAuth post-processing the server applies. This is the identical document a running instance serves at GET /api/api-docs/json (Swagger UI at /api/api-docs/swagger, ReDoc at /api/api-docs/redoc).
  note: 'Not fetched from a live host: SparkyFitness is self-hosted and the project operates no public instance, so the contract can only be read from the source that generates it. Upstream sets no operationIds; paths+methods are the stable identifiers.'
  upstream_version: server package.json 1.6.4 (release v1.6.4, 2026-08-27)