openapi: 3.0.3
info:
  title: The Quantum Club API
  description: "Public integration surface of The Quantum Club: SCIM 2.0
    provisioning and webhooks. Generated from the production contract —
    endpoints outside this spec are not part of the public API."
  version: 1.0.0
  contact:
    name: The Quantum Club Support
    email: support@thequantumclub.com
    url: https://thequantumclub.com/support
  license:
    name: Proprietary
    url: https://thequantumclub.com/terms
servers:
  - url: https://chgrkvftjfibufoopmav.supabase.co/functions/v1
    description: Production API
tags:
  - name: SCIM
    description: SCIM 2.0 provisioning endpoints for IdP integration
  - name: Webhooks
    description: Webhook management and delivery
paths:
  /scim-service-provider-config:
    get:
      tags:
        - SCIM
      summary: Get SCIM Service Provider Configuration
      description: Returns the SCIM 2.0 service provider configuration
      operationId: getScimServiceProviderConfig
      responses:
        "200":
          description: Service provider configuration
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/SCIMServiceProviderConfig"
  /scim-users:
    get:
      tags:
        - SCIM
      summary: List SCIM Users
      description: List users with optional SCIM filter
      operationId: listScimUsers
      security:
        - ScimTokenAuth: []
      parameters:
        - name: filter
          in: query
          description: SCIM filter expression (e.g., userName eq "user@example.com")
          schema:
            type: string
        - name: startIndex
          in: query
          schema:
            type: integer
            default: 1
        - name: count
          in: query
          schema:
            type: integer
            default: 100
            maximum: 100
      responses:
        "200":
          description: List of users
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/SCIMUserListResponse"
        "401":
          $ref: "#/components/responses/SCIMUnauthorized"
    post:
      tags:
        - SCIM
      summary: Create SCIM User
      description: Provision a new user via SCIM
      operationId: createScimUser
      security:
        - ScimTokenAuth: []
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: "#/components/schemas/SCIMUser"
      responses:
        "201":
          description: User created
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/SCIMUser"
        "409":
          $ref: "#/components/responses/SCIMConflict"
  /scim-users/{userId}:
    get:
      tags:
        - SCIM
      summary: Get SCIM User
      operationId: getScimUser
      security:
        - ScimTokenAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: User details
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/SCIMUser"
        "404":
          $ref: "#/components/responses/SCIMNotFound"
    put:
      tags:
        - SCIM
      summary: Replace SCIM User
      operationId: replaceScimUser
      security:
        - ScimTokenAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: "#/components/schemas/SCIMUser"
      responses:
        "200":
          description: User updated
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/SCIMUser"
    patch:
      tags:
        - SCIM
      summary: Patch SCIM User
      description: Partially update a user using SCIM PATCH operations
      operationId: patchScimUser
      security:
        - ScimTokenAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: "#/components/schemas/SCIMPatchRequest"
      responses:
        "200":
          description: User updated
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/SCIMUser"
    delete:
      tags:
        - SCIM
      summary: Delete SCIM User
      description: Deactivate a user (soft delete)
      operationId: deleteScimUser
      security:
        - ScimTokenAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: User deactivated
  /scim-groups:
    get:
      tags:
        - SCIM
      summary: List SCIM Groups
      operationId: listScimGroups
      security:
        - ScimTokenAuth: []
      parameters:
        - name: filter
          in: query
          schema:
            type: string
        - name: startIndex
          in: query
          schema:
            type: integer
            default: 1
        - name: count
          in: query
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: List of groups
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/SCIMGroupListResponse"
    post:
      tags:
        - SCIM
      summary: Create SCIM Group
      operationId: createScimGroup
      security:
        - ScimTokenAuth: []
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: "#/components/schemas/SCIMGroup"
      responses:
        "201":
          description: Group created
          content:
            application/scim+json:
              schema:
                $ref: "#/components/schemas/SCIMGroup"
  /webhook-dispatcher:
    post:
      tags:
        - Webhooks
      summary: Dispatch webhook
      description: Send a webhook to registered endpoints
      operationId: dispatchWebhook
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookPayload"
      responses:
        "200":
          description: Webhook dispatched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDispatchResult"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token from Supabase Auth
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for server-to-server integrations
    ScimTokenAuth:
      type: http
      scheme: bearer
      description: SCIM bearer token for IdP provisioning
  schemas:
    SCIMServiceProviderConfig:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        patch:
          type: object
          properties:
            supported:
              type: boolean
        bulk:
          type: object
          properties:
            supported:
              type: boolean
        filter:
          type: object
          properties:
            supported:
              type: boolean
            maxResults:
              type: integer
        authenticationSchemes:
          type: array
          items:
            type: object
    SCIMUser:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
            - urn:ietf:params:scim:schemas:core:2.0:User
        id:
          type: string
          format: uuid
        externalId:
          type: string
        userName:
          type: string
        name:
          type: object
          properties:
            formatted:
              type: string
            familyName:
              type: string
            givenName:
              type: string
        displayName:
          type: string
        emails:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                format: email
              primary:
                type: boolean
              type:
                type: string
        active:
          type: boolean
        meta:
          type: object
          properties:
            resourceType:
              type: string
            created:
              type: string
              format: date-time
            lastModified:
              type: string
              format: date-time
            location:
              type: string
              format: uri
    SCIMUserListResponse:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        totalResults:
          type: integer
        startIndex:
          type: integer
        itemsPerPage:
          type: integer
        Resources:
          type: array
          items:
            $ref: "#/components/schemas/SCIMUser"
    SCIMGroup:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        id:
          type: string
          format: uuid
        externalId:
          type: string
        displayName:
          type: string
        members:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                format: uuid
              display:
                type: string
              $ref:
                type: string
                format: uri
        meta:
          type: object
    SCIMGroupListResponse:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        totalResults:
          type: integer
        startIndex:
          type: integer
        itemsPerPage:
          type: integer
        Resources:
          type: array
          items:
            $ref: "#/components/schemas/SCIMGroup"
    SCIMPatchRequest:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        Operations:
          type: array
          items:
            type: object
            properties:
              op:
                type: string
                enum:
                  - add
                  - remove
                  - replace
              path:
                type: string
              value:
                oneOf:
                  - type: string
                  - type: boolean
                  - type: object
    WebhookPayload:
      type: object
      required:
        - event
        - data
      properties:
        event:
          type: string
          example: application.created
        data:
          type: object
    WebhookDispatchResult:
      type: object
      properties:
        success:
          type: boolean
        deliveries:
          type: array
          items:
            type: object
            properties:
              endpoint:
                type: string
              status:
                type: integer
              success:
                type: boolean
    SCIMError:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        detail:
          type: string
        status:
          type: integer
        scimType:
          type: string
  responses:
    SCIMUnauthorized:
      description: SCIM unauthorized
      content:
        application/scim+json:
          schema:
            $ref: "#/components/schemas/SCIMError"
    SCIMNotFound:
      description: SCIM resource not found
      content:
        application/scim+json:
          schema:
            $ref: "#/components/schemas/SCIMError"
    SCIMConflict:
      description: SCIM resource conflict
      content:
        application/scim+json:
          schema:
            $ref: "#/components/schemas/SCIMError"