Netcore Cloud Auth API

openapi: 3.2.0
info:
  title: Orbit Router Auth API
  version: 1.0.0
  description: Complete API specification for the Orbit Router email routing platform.
  contact:
    name: Orbit Engineering
  license:
    name: Proprietary
servers:
- url: https://orbitus.netcorecloud.com
  description: Production — Orbit Engine (HTTP Relay)
- url: https://orbitus.netcorecloud.com/apiorbit
  description: Production — Orbit Backend (Config & Management)
security: []
tags:
- name: Auth
paths:
  /auth/password:
    put:
      operationId: changePassword
      tags:
      - Auth
      summary: Change own password
      security:
      - BackendJWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - new_password
              properties:
                new_password:
                  type: string
                  format: password
      responses:
        '200':
          description: Password changed.
        '401':
          description: Unauthorized.
  /auth/check-account:
    get:
      operationId: checkAccount
      tags:
      - Auth
      summary: Check if account exists
      security: []
      parameters:
      - name: name
        in: query
        required: true
        schema:
          type: string
        description: Account name to check.
      responses:
        '200':
          description: Account existence result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  exists:
                    type: boolean
  /auth/2fa/disable:
    post:
      operationId: disable2FA
      tags:
      - Auth
      summary: Disable two-factor authentication
      security:
      - BackendJWT: []
      responses:
        '200':
          description: 2FA disabled.
  /auth/forgot-password:
    post:
      operationId: forgotPassword
      tags:
      - Auth
      summary: Request password reset
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - accountName
              - email
              properties:
                accountName:
                  type: string
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: Reset token generated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
  /auth/profile:
    get:
      operationId: getProfile
      tags:
      - Auth
      summary: Get authenticated user profile
      security:
      - BackendJWT: []
      responses:
        '200':
          description: User profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
  /auth/login:
    post:
      operationId: login
      tags:
      - Auth
      summary: Login
      description: 'Authenticate a user. Returns JWT access token and refresh token.

        Rate limited to 5 attempts per IP per 5 minutes.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful (or 2FA required).
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/LoginResponse'
                - $ref: '#/components/schemas/TwoFactorRequiredResponse'
        '400':
          description: Missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendErrorResponse'
        '401':
          description: Invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendErrorResponse'
        '429':
          description: Rate limited.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendErrorResponse'
  /auth/logout:
    post:
      operationId: logout
      tags:
      - Auth
      summary: Logout (revoke token)
      security:
      - BackendJWT: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  description: Optional; also revokes the refresh token.
      responses:
        '200':
          description: Logged out successfully.
  /auth/refresh:
    post:
      operationId: refreshToken
      tags:
      - Auth
      summary: Refresh JWT token
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - refresh_token
              properties:
                refresh_token:
                  type: string
      responses:
        '200':
          description: New JWT and refresh token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid or expired refresh token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendErrorResponse'
  /auth/reset-password:
    post:
      operationId: resetPassword
      tags:
      - Auth
      summary: Reset password with token
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - token
              - password
              properties:
                token:
                  type: string
                password:
                  type: string
                  format: password
      responses:
        '200':
          description: Password reset successful.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
  /auth/2fa/setup:
    post:
      operationId: setup2FA
      tags:
      - Auth
      summary: Setup two-factor authentication
      description: Generates a TOTP secret, QR code, and provisioning URI.
      security:
      - BackendJWT: []
      responses:
        '200':
          description: 2FA setup data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TwoFactorSetupResponse'
  /auth/signup:
    post:
      operationId: signup
      tags:
      - Auth
      summary: Register new account
      description: Creates a client and admin user. Returns JWT immediately.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupRequest'
      responses:
        '200':
          description: Account created; JWT returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '400':
          description: Validation error (duplicate account name or email).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendErrorResponse'
  /auth/2fa/verify:
    post:
      operationId: verify2FA
      tags:
      - Auth
      summary: Verify TOTP code
      description: 'Verify a TOTP code. Used for both setup confirmation (`setup: true`) and login

        verification. When `setup: true`, returns backup codes. During login, returns the

        full login response.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TwoFactorVerifyRequest'
      responses:
        '200':
          description: Verification successful.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TwoFactorSetupConfirmResponse'
                - $ref: '#/components/schemas/LoginResponse'
components:
  schemas:
    BackendErrorResponse:
      type: object
      properties:
        error:
          type: string
        field:
          type: string
          description: Optional field that caused the error.
    LoginRequest:
      type: object
      required:
      - account_name
      - password
      properties:
        account_name:
          type: string
          description: Client/workspace name from `client_details.clientname`.
        username:
          type: string
          description: Username (provide either `username` or `email`).
        email:
          type: string
          format: email
          description: Alternative to `username`.
        password:
          type: string
          format: password
    SignupRequest:
      type: object
      required:
      - accountName
      - fullName
      - email
      - password
      properties:
        accountName:
          type: string
          description: Unique account name.
        fullName:
          type: string
        email:
          type: string
          format: email
          description: Unique across all users (case-insensitive).
        password:
          type: string
          format: password
    TwoFactorRequiredResponse:
      type: object
      properties:
        two_factor_required:
          type: boolean
          example: true
        user_id:
          type: integer
        client_id:
          type: integer
    TwoFactorSetupResponse:
      type: object
      properties:
        secret:
          type: string
          description: TOTP secret key.
          example: JBSWY3DPEHPK3PXP
        provisioning_uri:
          type: string
          description: OTP auth URI for authenticator apps.
        qr_code:
          type: string
          description: Base64-encoded QR code image (data URI).
    LoginResponse:
      type: object
      properties:
        token:
          type: string
          description: JWT access token (15-minute lifetime).
        refresh_token:
          type: string
          description: Refresh token (7-day lifetime).
        refresh_expires_at:
          type: string
          format: date-time
        client_id:
          type: integer
        clients:
          type: array
          items:
            $ref: '#/components/schemas/ClientSummary'
        is_parent:
          type: boolean
        user:
          $ref: '#/components/schemas/UserProfile'
    UserProfile:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        email:
          type: string
          format: email
        full_name:
          type: string
        role:
          type: string
          enum:
          - admin
          - viewer
        client_id:
          type: integer
        two_factor_enabled:
          type: boolean
    ClientSummary:
      type: object
      properties:
        client_id:
          type: integer
        clientname:
          type: string
        status:
          type: string
          enum:
          - active
          - inactive
    TwoFactorSetupConfirmResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        backup_codes:
          type: array
          items:
            type: string
          description: One-time backup codes; store securely.
    TwoFactorVerifyRequest:
      type: object
      required:
      - user_id
      - client_id
      - code
      properties:
        user_id:
          type: integer
        client_id:
          type: integer
        code:
          type: string
          description: 6-digit TOTP code.
          pattern: ^\d{6}$
        setup:
          type: boolean
          default: false
          description: Set to `true` during initial 2FA setup confirmation.
  securitySchemes:
    BackendJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT token obtained from `POST /auth/login`. Access token lifetime: 15 minutes.

        Claims: `user_id`, `client_id`, `role`, `jti`, `exp`, `iat`.

        '
    EngineApiKeyBearer:
      type: http
      scheme: bearer
      description: 'Engine API key via `Authorization: Bearer <api_key>` (priority 1).'
    EngineApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Engine API key via `X-API-Key` header (priority 2).
    EngineApiKeyFallback:
      type: apiKey
      in: header
      name: api_key
      description: Engine API key via `api_key` header (priority 3, fallback).
x-readme:
  explorer-enabled: true
  proxy-enabled: true
x-provenance:
  method: searched
  source: https://emaildocs.netcorecloud.com/reference
  note: Verbatim OpenAPI fragments embedded in each ReadMe reference page on emaildocs.netcorecloud.com, merged by path. Not authored by API Evangelist.
  retrieved: '2026-10-13'