openapi: 3.0.3
info:
  title: Switchboard Core API
  description: |
    Self-hosted extension platform. Identity, teams, permissions, workflows,
    and a package system. Everything else ships as installable extensions.

    ## Authentication

    Three authentication modes, selected by the `AUTH_MODE` environment variable.
    All three produce the same JWT-based session.

    **Builtin (default):** Username/password via `POST /api/v1/auth/login`.

    **mTLS:** Client certificate presented via reverse proxy headers.

    **OIDC:** Authorization code flow against an external IdP (e.g. Keycloak).

    Access tokens expire in 15 minutes. Refresh tokens expire in 7 days.
    Use `POST /api/v1/auth/refresh` to rotate.

  version: '${VERSION}'

servers:
  - url: '{scheme}://{host}{basePath}'
    variables:
      scheme:
        default: https
      host:
        default: localhost:8080
      basePath:
        default: ''

paths:
  /health:
    get:
      summary: Health check
      operationId: healthCheck
      tags: [System]
      responses:
        '200':
          description: OK

  /api/v1/auth/login:
    post:
      summary: Login (builtin auth)
      operationId: login
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                login:
                  type: string
                password:
                  type: string
              required: [login, password]
      responses:
        '200':
          description: JWT tokens returned

  /api/v1/auth/register:
    post:
      summary: Register new user (builtin auth)
      operationId: register
      tags: [Auth]
      responses:
        '201':
          description: User created

  /api/v1/auth/refresh:
    post:
      summary: Refresh access token
      operationId: refreshToken
      tags: [Auth]
      responses:
        '200':
          description: New token pair

  /api/v1/auth/oidc/login:
    get:
      summary: Initiate OIDC login
      operationId: oidcLogin
      tags: [Auth]
      responses:
        '302':
          description: Redirect to IdP

  /api/v1/auth/oidc/callback:
    get:
      summary: OIDC callback
      operationId: oidcCallback
      tags: [Auth]
      responses:
        '200':
          description: JWT tokens returned

# ═══════════════════════════════════════════════════════
# TODO: Step 8 — Generate full kernel-only ICD from
# the route registrations in main.go. This stub keeps
# /api/docs functional during the transition.
# ═══════════════════════════════════════════════════════