robosystems-ai Auth: SSO API

openapi: 3.2.0
info:
  title: 'RoboSystems Auth: SSO API'
  description: 'The REST and GraphQL API for RoboSystems — an open-source, AI-native platform for accounting, financial reporting and investment management. It powers RoboLedger and RoboInvestor.


    ## Two surfaces


    **Platform** — `/v1/…` — graphs, queries, schema, documents, search, memory, connections, billing and access. Reads are REST `GET`s; every write is a named operation at `/operations/{name}` returning an `OperationEnvelope`, accepting an `Idempotency-Key`, and streaming progress at `/v1/operations/{id}/stream`.

    → API reference


    **Extensions** — `/extensions/…` — RoboLedger and RoboInvestor, scoped by `graph_id` in the URL. Reads are GraphQL at `POST /extensions/{graph_id}/graphql` and change nothing; writes are named operations at `/extensions/{domain}/{graph_id}/operations/{name}`; analytical views read the materialized graph.

    → Extensions reference · every GraphQL query


    ## Authenticating


    `X-API-Key: rfs…` on REST, GraphQL and per-graph MCP. Browser sessions use JWTs from `POST /v1/auth/login`. The graph-agnostic MCP endpoint `/v1/mcp` takes OAuth 2.1 bearer tokens only.


    ## Connecting an AI client


    Every graph is an MCP server at `POST /v1/graphs/{graph_id}/mcp`, and `POST /v1/mcp` serves OAuth clients that pick their graph at consent.

    → MCP guide


    ## Clients


    `robosystems-client` for Python, `@robosystems/client` for TypeScript.

    → Guides · Technical docs'
  version: 1.20.6
tags:
- name: 'Auth: SSO'
  description: 🎫 Single sign-on - Cross-app token exchange, and enterprise OIDC where enabled
paths:
  /v1/auth/sso-token:
    post:
      tags:
      - 'Auth: SSO'
      summary: Generate SSO Token
      description: Step 1 of 3 in the cross-app SSO flow. Issues a single-use token (5 minute TTL) for handoff to a target application.
      operationId: generateSSOToken
      parameters:
      - name: auth-token
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Auth-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOTokenResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/sso-exchange:
    post:
      tags:
      - 'Auth: SSO'
      summary: SSO Token Exchange
      description: Step 2 of 3. Exchanges the SSO token for a short-lived session ID. Avoids passing tokens in redirect URLs.
      operationId: ssoTokenExchange
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSOExchangeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOExchangeResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/sso-complete:
    post:
      tags:
      - 'Auth: SSO'
      summary: Complete SSO Authentication
      description: Step 3 of 3. Exchanges the session ID for a full JWT token. Called by the target app after redirect.
      operationId: completeSSOAuth
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSOCompleteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SSOTokenResponse:
      properties:
        token:
          type: string
          title: Token
          description: Temporary SSO token for cross-app authentication
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: Token expiration time
        apps:
          items:
            type: string
          type: array
          title: Apps
          description: Available apps for this user
      type: object
      required:
      - token
      - expires_at
      - apps
      title: SSOTokenResponse
      description: SSO token response model.
    SSOExchangeRequest:
      properties:
        token:
          type: string
          title: Token
          description: Temporary SSO token
        target_app:
          type: string
          title: Target App
          description: Target application identifier
        return_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Return Url
          description: Optional return URL after authentication
        browser_nonce_hash:
          anyOf:
          - type: string
            pattern: ^[0-9a-f]{64}$
          - type: 'null'
          title: Browser Nonce Hash
          description: SHA-256 (hex) of a nonce the target app minted in the browser that is signing in. Completion must present the nonce, so the handoff cannot be redeemed by any other browser; a session exchanged without one cannot be completed.
      type: object
      required:
      - token
      - target_app
      title: SSOExchangeRequest
      description: SSO token exchange request model.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable error message explaining what went wrong
          examples:
          - Insufficient credits for operation
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
          description: Machine-readable error code for programmatic handling
          examples:
          - INSUFFICIENT_CREDITS
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
          description: Unique request ID for tracking and debugging
          examples:
          - req_1234567890abcdef
        timestamp:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Timestamp
          description: Timestamp when the error occurred
          examples:
          - '2024-01-01T00:00:00Z'
      type: object
      required:
      - detail
      title: ErrorResponse
      description: Error body returned by every endpoint.
      example:
        code: RESOURCE_NOT_FOUND
        detail: Resource not found
        request_id: req_1234567890abcdef
        timestamp: '2024-01-01T00:00:00Z'
    AuthResponse:
      properties:
        user:
          additionalProperties: true
          type: object
          title: User
          description: User information
        org:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Org
          description: Organization information (personal org created automatically on registration)
        message:
          type: string
          title: Message
          description: Success message
        status:
          type: string
          enum:
          - authenticated
          - mfa_required
          - mfa_enrollment_required
          title: Status
          description: 'Login flow state: authenticated (token present), or a passkey MFA step is required before a session is issued (mfa_token present)'
          default: authenticated
        mfa_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Mfa Token
          description: Short-lived token authorizing the MFA second step or forced enrollment; present only when status is not 'authenticated'
        token:
          anyOf:
          - type: string
          - type: 'null'
          title: Token
          description: JWT authentication token (optional for cookie-based auth)
        expires_in:
          anyOf:
          - type: integer
          - type: 'null'
          title: Expires In
          description: Token expiry time in seconds from now
        refresh_threshold:
          anyOf:
          - type: integer
          - type: 'null'
          title: Refresh Threshold
          description: Recommended refresh threshold in seconds before expiry
      type: object
      required:
      - user
      - message
      title: AuthResponse
      description: Authentication response model.
    SSOExchangeResponse:
      properties:
        session_id:
          type: string
          title: Session Id
          description: Temporary session ID for secure handoff
        redirect_url:
          type: string
          title: Redirect Url
          description: URL to redirect to for authentication
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: Session expiration time
      type: object
      required:
      - session_id
      - redirect_url
      - expires_at
      title: SSOExchangeResponse
      description: SSO token exchange response model.
    SSOCompleteRequest:
      properties:
        session_id:
          type: string
          title: Session Id
          description: Temporary session ID from secure handoff
        browser_nonce:
          anyOf:
          - type: string
            maxLength: 128
            minLength: 16
          - type: 'null'
          title: Browser Nonce
          description: The nonce this browser minted when it started the bridge; its SHA-256 was passed through the exchange as browser_nonce_hash. Required to complete a handoff.
      type: object
      required:
      - session_id
      title: SSOCompleteRequest
      description: SSO completion request model.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT bearer token