Insforge Admin API

openapi: 3.0.3
info:
  title: Insforge AI Admin API
  version: 1.0.0
  description: Model Gateway helper APIs for OpenRouter key provisioning, model discovery, and deprecated compatibility proxy routes
tags:
- name: Admin
paths:
  /api/ai/models:
    get:
      summary: Get all available AI models
      description: Returns the normalized OpenRouter model catalog fetched from OpenRouter with output_modalities=all.
      tags:
      - Admin
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Flat array of available models from the OpenRouter catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
        '401':
          description: Unauthorized
        '500':
          description: Failed to get models list
  /api/ai/overview:
    get:
      summary: Get Model Gateway overview
      description: Returns key-level OpenRouter usage and activity time series when the key has activity access.
      tags:
      - Admin
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Model Gateway overview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIOverview'
        '401':
          description: Unauthorized
        '500':
          description: Failed to fetch overview
  /api/ai/{provider}/api-key:
    get:
      summary: Get active provider API key
      description: Returns the active provider API key details for admin copy workflows. Currently only `openrouter` is supported.
      tags:
      - Admin
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/AIProvider'
      responses:
        '200':
          description: Active provider API key details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenRouterKeyResponse'
        '400':
          description: Missing or unsupported provider API key
        '401':
          description: Unauthorized
        '500':
          description: Failed to fetch API key details
  /api/ai/{provider}/api-key/rotate:
    post:
      summary: Rotate provider API key
      description: Rotate the active provider API key for cloud-managed Model Gateway credentials. Currently only `openrouter` is supported.
      tags:
      - Admin
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/AIProvider'
      responses:
        '200':
          description: API key rotated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenRouterKeyResponse'
        '400':
          description: Unsupported provider
        '401':
          description: Unauthorized
        '500':
          description: Failed to rotate API key
  /api/auth/config:
    get:
      summary: Get authentication configuration
      description: Get current authentication settings including all configuration options (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Authentication configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  requireEmailVerification:
                    type: boolean
                  passwordMinLength:
                    type: integer
                    minimum: 4
                    maximum: 128
                  requireNumber:
                    type: boolean
                  requireLowercase:
                    type: boolean
                  requireUppercase:
                    type: boolean
                  requireSpecialChar:
                    type: boolean
                  verifyEmailMethod:
                    type: string
                    enum:
                    - code
                    - link
                    description: Method for email verification (code = 6-digit OTP, link = magic link)
                  resetPasswordMethod:
                    type: string
                    enum:
                    - code
                    - link
                    description: Method for password reset (code = 6-digit OTP + exchange flow, link = magic link)
                  allowedRedirectUrls:
                    type: array
                    items:
                      type: string
                    description: List of allowed URLs for authentication redirects. If empty, all redirects are allowed for smoother development UX. This is not recommended in production.
                  disableSignup:
                    type: boolean
                    description: When true, public sign-up endpoints (POST /api/auth/users and first-time OAuth) are rejected with 403 AUTH_SIGNUP_DISABLED. Admin-authenticated user creation is unaffected.
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
    put:
      summary: Update authentication configuration
      description: Update authentication settings (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                requireEmailVerification:
                  type: boolean
                passwordMinLength:
                  type: integer
                  minimum: 4
                  maximum: 128
                requireNumber:
                  type: boolean
                requireLowercase:
                  type: boolean
                requireUppercase:
                  type: boolean
                requireSpecialChar:
                  type: boolean
                verifyEmailMethod:
                  type: string
                  enum:
                  - code
                  - link
                  description: Method for email verification (code = 6-digit OTP, link = magic link)
                resetPasswordMethod:
                  type: string
                  enum:
                  - code
                  - link
                  description: Method for password reset (code = 6-digit OTP + exchange flow, link = magic link)
                allowedRedirectUrls:
                  type: array
                  items:
                    type: string
                  description: List of allowed URLs for authentication redirects. If empty, all redirects are allowed for smoother development UX. This is not recommended in production.
                disableSignup:
                  type: boolean
                  description: When true, public sign-up endpoints (POST /api/auth/users and first-time OAuth) are rejected with 403 AUTH_SIGNUP_DISABLED. Admin-authenticated user creation is unaffected.
      responses:
        '200':
          description: Configuration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  requireEmailVerification:
                    type: boolean
                  passwordMinLength:
                    type: integer
                    minimum: 4
                    maximum: 128
                  requireNumber:
                    type: boolean
                  requireLowercase:
                    type: boolean
                  requireUppercase:
                    type: boolean
                  requireSpecialChar:
                    type: boolean
                  verifyEmailMethod:
                    type: string
                    enum:
                    - code
                    - link
                  resetPasswordMethod:
                    type: string
                    enum:
                    - code
                    - link
                  allowedRedirectUrls:
                    type: array
                    items:
                      type: string
                    description: List of allowed URLs for authentication redirects. If empty, all redirects are allowed for smoother development UX. This is not recommended in production.
                  disableSignup:
                    type: boolean
                    description: When true, public sign-up endpoints (POST /api/auth/users and first-time OAuth) are rejected with 403 AUTH_SIGNUP_DISABLED. Admin-authenticated user creation is unaffected.
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
  /api/auth/users:
    get:
      summary: List all users (admin only)
      description: Returns paginated list of users
      tags:
      - Admin
      security:
      - bearerAuth: []
      parameters:
      - name: offset
        in: query
        schema:
          type: string
          default: '0'
        description: Number of records to skip
      - name: limit
        in: query
        schema:
          type: string
          default: '10'
        description: Maximum number of records to return
      - name: search
        in: query
        schema:
          type: string
        description: Search by email or name
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserResponse'
                  pagination:
                    type: object
                    properties:
                      offset:
                        type: integer
                      limit:
                        type: integer
                      total:
                        type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
    delete:
      summary: Delete users (admin only)
      description: Delete multiple users by their IDs
      tags:
      - Admin
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userIds:
                  type: array
                  items:
                    type: string
              required:
              - userIds
      responses:
        '200':
          description: Users deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  deletedCount:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
  /api/auth/users/{userId}:
    get:
      summary: Get specific user
      description: Get user details by ID (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: User ID
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Invalid user ID format
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
        '404':
          description: User not found
  /api/auth/admin/sessions:
    post:
      summary: Admin login
      description: Authenticates admin user for dashboard access
      tags:
      - Admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - username
              - password
              properties:
                username:
                  type: string
                  example: admin
                password:
                  type: string
      responses:
        '200':
          description: Admin login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  projectAdmin:
                    $ref: '#/components/schemas/ProjectAdminResponse'
                  accessToken:
                    type: string
                  csrfToken:
                    type: string
                    description: CSRF token for `/api/auth/admin/refresh`
        '401':
          description: Invalid credentials
        '403':
          description: User is not an admin
  /api/auth/admin/sessions/exchange:
    post:
      summary: Exchange cloud provider authorization code for admin session
      description: Verifies an authorization code/JWT from from Insforge Cloud platform and issues an internal admin session token with project_admin role
      tags:
      - Admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  description: Authorization code or JWT from the Insforge
                  example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      responses:
        '200':
          description: Cloud authorization verified, admin session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  projectAdmin:
                    $ref: '#/components/schemas/ProjectAdminResponse'
                  accessToken:
                    type: string
                    description: Internal JWT for admin authentication
                  csrfToken:
                    type: string
                    description: CSRF token for `/api/auth/admin/refresh`
        '400':
          description: Invalid authorization code or JWT verification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/admin/refresh:
    post:
      summary: Refresh admin dashboard access token
      description: Uses the dashboard-only httpOnly `insforge_admin_refresh_token` cookie with an `X-CSRF-Token` header.
      tags:
      - Admin
      parameters:
      - name: X-CSRF-Token
        in: header
        required: true
        schema:
          type: string
        description: CSRF token returned from admin login or admin refresh
      responses:
        '200':
          description: Admin token refreshed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  projectAdmin:
                    $ref: '#/components/schemas/ProjectAdminResponse'
                  accessToken:
                    type: string
                  csrfToken:
                    type: string
                    description: CSRF token for the next admin refresh request
        '401':
          description: No admin refresh token provided or project admin not found
        '403':
          description: Invalid CSRF token
  /api/auth/admin/logout:
    post:
      summary: Logout admin dashboard session
      description: 'Clears the dashboard-only `insforge_admin_refresh_token` cookie.


        If a valid admin refresh cookie is present, the request must include the `X-CSRF-Token`

        header returned from admin login, admin session exchange, or admin refresh. Missing, expired,

        invalid, or wrong-session-type admin refresh cookies are cleared idempotently and still return

        success.

        '
      tags:
      - Admin
      parameters:
      - name: X-CSRF-Token
        in: header
        schema:
          type: string
        description: CSRF token required when a valid admin refresh cookie is present
      responses:
        '200':
          description: Logged out successfully. Also returned when the admin refresh cookie is missing, expired, invalid, or the wrong session type.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '403':
          description: Invalid or missing CSRF token for a valid admin refresh cookie
  /api/auth/tokens/anon:
    post:
      summary: Get anon key (deprecated)
      deprecated: true
      description: Deprecated - use GET /api/metadata/anon-key instead. Returns the project's opaque anon key (`anon_...`) under the legacy `accessToken` field for backward compatibility. The anon key is a non-secret client identifier that maps requests to the `anon` role; it replaces the former non-expiring anonymous JWT and can be rotated via POST /api/secrets/anon-key/rotate (admin only).
      tags:
      - Admin
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Anon key retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                    description: Opaque anon key (legacy field name kept for compatibility)
                    example: anon_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd
                  message:
                    type: string
                    description: Success message
                    example: Anon key retrieved successfully (deprecated route, use GET /api/metadata/anon-key)
        '401':
          description: Unauthorized - requires authentication
        '403':
          description: Forbidden - admin access required
        '404':
          description: Anon key not initialized
  /api/auth/oauth/configs:
    get:
      summary: List all OAuth configurations
      description: Get all configured OAuth providers (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of OAuth configurations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthConfig'
                  count:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
    post:
      summary: Create OAuth configuration
      description: Create a new OAuth provider configuration (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - provider
              properties:
                provider:
                  type: string
                  enum:
                  - google
                  - github
                  - discord
                  - linkedin
                  - facebook
                  - instagram
                  - tiktok
                  - apple
                  - x
                  - spotify
                  - microsoft
                clientId:
                  type: string
                clientSecret:
                  type: string
                redirectUri:
                  type: string
                scopes:
                  type: array
                  items:
                    type: string
                useSharedKey:
                  type: boolean
      responses:
        '200':
          description: OAuth configuration created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthConfig'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
  /api/auth/oauth/{provider}/config:
    get:
      summary: Get OAuth configuration for specific provider
      description: Get OAuth configuration including client secret (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          enum:
          - google
          - github
          - discord
          - linkedin
          - facebook
          - instagram
          - tiktok
          - apple
          - x
          - spotify
          - microsoft
      responses:
        '200':
          description: OAuth configuration
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OAuthConfig'
                - type: object
                  properties:
                    clientSecret:
                      type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
        '404':
          description: Configuration not found
    put:
      summary: Update OAuth configuration
      description: Update OAuth provider configuration (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          enum:
          - google
          - github
          - discord
          - linkedin
          - facebook
          - instagram
          - tiktok
          - apple
          - x
          - spotify
          - microsoft
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                clientId:
                  type: string
                clientSecret:
                  type: string
                redirectUri:
                  type: string
                scopes:
                  type: array
                  items:
                    type: string
                useSharedKey:
                  type: boolean
      responses:
        '200':
          description: Configuration updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthConfig'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
        '404':
          description: Configuration not found
    delete:
      summary: Delete OAuth configuration
      description: Delete OAuth provider configuration (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          enum:
          - google
          - github
          - discord
          - linkedin
          - facebook
          - instagram
          - tiktok
          - apple
          - x
          - spotify
          - microsoft
      responses:
        '200':
          description: Configuration deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
        '404':
          description: Configuration not found
  /api/auth/oauth/custom/configs:
    get:
      summary: List all custom OAuth configurations
      description: Get all configured custom OAuth providers (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of custom OAuth configurations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomOAuthConfig'
                  count:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
    post:
      summary: Create custom OAuth configuration
      description: Create a new custom OAuth provider configuration (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - name
              - discoveryEndpoint
              - clientId
              - clientSecret
              properties:
                key:
                  type: string
                name:
                  type: string
                discoveryEndpoint:
                  type: string
                  format: uri
                clientId:
                  type: string
                clientSecret:
                  type: string
      responses:
        '200':
          description: Custom OAuth configuration created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomOAuthConfig'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
        '409':
          description: Configuration already exists
  /api/auth/oauth/custom/{key}/config:
    get:
      summary: Get custom OAuth configuration
      description: Get a custom OAuth configuration including client secret (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Custom OAuth configuration
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CustomOAuthConfig'
                - type: object
                  properties:
                    clientSecret:
                      type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
        '404':
          description: Configuration not found
    put:
      summary: Update custom OAuth configuration
      description: Update a custom OAuth provider configuration (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                discoveryEndpoint:
                  type: string
                  format: uri
                clientId:
                  type: string
                clientSecret:
                  type: string
      responses:
        '200':
          description: Custom OAuth configuration updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomOAuthConfig'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
        '404':
          description: Configuration not found
    delete:
      summary: Delete custom OAuth configuration
      description: Delete a custom OAuth provider configuration (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Configuration deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
        '404':
          description: Configuration not found
  /api/auth/admin/sessions/current:
    get:
      summary: Get current admin session
      description: Returns the currently authenticated admin's basic info from the access token.
      tags:
      - Admin
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Current admin session info
          content:
            application/json:
              schema:
                type: object
                properties:
                  admin:
                    type: object
                    properties:
                      sub:
                        type: string
                        description: Admin subject identifier
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin access required
  /api/auth/smtp-config:
    get:
      summary: Get SMTP configuration
      description: Get current SMTP email configuration (admin only)
      tags:
      - Admin
      security:
      - bearerAuth: []
      x-internal: true
      responses:
        '200':
          description: SMTP configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmtpConfig'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Admin only
    put:
      summary: Update SMTP configuration
      description: 'Create or update SMTP email configuration (admin only).

        When `enabled` is true, the fields `host`, `username`, `senderEmail`, and `senderName` are required by the backend validation.

        When `enabled` is false, these fields may be empty.

        '
      tags:
      - Admin
      security:
      - bearerAuth: []
      x-internal: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - enabled
              - port
              properties:
                enabled:
                  type: boolean
                  description: When true, host/username/senderEmail/senderName become required
                host:
                  type: string
                  description: Required when enabled is true
                port:
                  type: integer
                  enum:
                  - 25
                  - 465
                  - 587
                  - 2525
                username:
                  type: string
                  description: Required when enabled is true
                password:
                  type: string
                  description: SMTP password (optional on update if unchanged)
                senderEmail:
                  type: string
                  format: email
                  description: Required when enabled is true
                senderName:
                  type:

# --- truncated at 32 KB (145 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/insforge/refs/heads/main/openapi/insforge-admin-api-openapi.yml