Sageox Auth API

openapi: 3.2.0
info:
  title: SageOx Auth API
  version: 1.0.0
  description: '# API Reference


    ## Overview


    SageOx is a platform that captures team knowledge from discussions, decisions, and work context into a Ledger (per-repo historical record) and Team Context (team-wide shared knowledge).'
  contact:
    name: SageOx Team
  license:
    name: MIT
servers:
- url: http://localhost:3000
  description: Devcontainer
- url: https://test.sageox.ai
  description: Test
- url: https://sageox.ai
  description: Production
security:
- bearerAuth: []
tags:
- name: Auth
  description: Session management and token lifecycle. Validates JWT tokens issued by Better Auth, returns session details and user identity. Used by both web app and CLI for authentication verification.
paths:
  /api/v1/auth/session:
    get:
      summary: Get current session
      description: Retrieves the current authenticated session and user information
      operationId: getSession
      tags:
      - Auth
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Session retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - session
                - user
                properties:
                  session:
                    type: object
                    required:
                    - id
                    - expiresAt
                    properties:
                      id:
                        type: string
                        description: Session identifier
                        example: 01234567-89ab-cdef-0123-456789abcdef
                      expiresAt:
                        type: string
                        format: date-time
                        description: Session expiration timestamp
                        example: '2025-12-03T18:00:00Z'
                  user:
                    type: object
                    required:
                    - id
                    - email
                    properties:
                      id:
                        type: string
                        description: User identifier
                        example: 01234567-89ab-cdef-0123-456789abcdef
                      email:
                        type: string
                        format: email
                        description: User email address
                        example: user@example.com
                      name:
                        type: string
                        nullable: true
                        description: User display name
                        example: John Doe
        '401':
          description: Unauthorized - invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/auth/signout:
    post:
      summary: Sign out
      description: Terminates the current authenticated session
      operationId: signOut
      tags:
      - Auth
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Successfully signed out
          content:
            application/json:
              schema:
                type: object
                required:
                - signedOut
                properties:
                  signedOut:
                    type: boolean
                    description: Indicates successful sign out
                    example: true
        '401':
          description: Unauthorized - invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      description: Standard error response returned by all endpoints on failure.
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          description: Always `false` for error responses.
          enum:
          - false
        error:
          type: string
          description: Human-readable error message describing what went wrong. Do not parse this programmatically — use HTTP status codes for control flow.
          example: Invalid request parameters
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT token obtained from the auth service (/api/auth/token).

        Token is validated using JWKS from the auth service.

        Required claims: sub (user_id), email, name, tier.

        '