byom-customer-api/docs/openapi.yaml

openapi: 3.0.0
info:
  title: BYOM Core API
  version: '1.0'
  description: API for managing BYOM Core services
  contact:
    name: BYOM Support
servers:
  - url: /api/v1/core
    description: BYOM Core API

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          example: "Error message description"

    Message:
      type: object
      properties:
        message:
          type: string
          example: "Success message description"

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        phone_number:
          type: string
        role:
          type: string
          enum: [owner, admin, member]
        status:
          type: string
          enum: [active, pending, inactive]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Workspace:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Profile:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        workspace_id:
          type: string
          format: uuid

    Invite:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        workspace_id:
          type: string
          format: uuid
        role:
          type: string
          enum: [owner, admin, member]
        status:
          type: string
          enum: [pending, accepted, expired, cancelled]
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time

paths:
  /health:
    get:
      summary: Health check endpoint
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"

  /auth/login:
    post:
      summary: Authenticate user
      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:
                  token:
                    type: string
                  user:
                    $ref: '#/components/schemas/User'
        '400':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/current:
    get:
      summary: Get current user information
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Current user information
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  workspaces:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
    put:
      summary: Update current user
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                phone_number:
                  type: string
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'

  /workspaces:
    post:
      summary: Create new workspace
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
      responses:
        '201':
          description: Workspace created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'

  /workspaces/owners/init:
    post:
      summary: Initialize workspace owner
      description: First step of workspace owner creation - creates a pending owner account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                phone_number:
                  type: string
      responses:
        '201':
          description: Workspace owner initialized
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: User already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /workspaces/owners:
    put:
      summary: Complete workspace owner creation
      description: Second step of workspace owner creation - sets password and activates the account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
                - password
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                phone_number:
                  type: string
                password:
                  type: string
                  format: password
      responses:
        '201':
          description: Workspace owner created
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Pending owner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Email does not match pending owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /workspaces/{id}/members:
    post:
      summary: Add member to workspace
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum: [admin, member]
      responses:
        '200':
          description: Member added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'

  /profiles:
    get:
      summary: List profiles
      security:
        - BearerAuth: []
      responses:
        '200':
          description: List of profiles
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile'
    post:
      summary: Create new profile
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - workspace_id
              properties:
                name:
                  type: string
                workspace_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Profile created
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile:
                    $ref: '#/components/schemas/Profile'

  /profiles/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get profile by ID
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Profile details
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile:
                    $ref: '#/components/schemas/Profile'
    put:
      summary: Update profile
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
      responses:
        '200':
          description: Profile updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile:
                    $ref: '#/components/schemas/Profile'
    delete:
      summary: Delete profile
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Profile deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'

  /invitations:
    post:
      summary: Create invitation
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - workspace_id
                - role
              properties:
                email:
                  type: string
                  format: email
                workspace_id:
                  type: string
                  format: uuid
                role:
                  type: string
                  enum: [admin, member]
      responses:
        '201':
          description: Invitation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invite'

  /invitations/accept:
    post:
      summary: Accept invitation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
                - password
                - token
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                phone_number:
                  type: string
                password:
                  type: string
                  format: password
                token:
                  type: string
      responses:
        '201':
          description: Invitation accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  workspace_id:
                    type: string
                    format: uuid

  /invitations/validate:
    get:
      summary: Validate invitation token
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Token validation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  workspace_id:
                    type: string
                    format: uuid
                  email:
                    type: string
                    format: email