Super.ai service-accounts API

openapi: 3.1.0
info:
  title: SuperAI Flow Platform auth service-accounts API
  description: "SuperAI Flows is a workflow orchestration platform that enables you to design, deploy, and monitor automated workflows at scale.\n\nBuild complex workflows using our declarative YAML DSL, execute them reliably, and integrate seamlessly with AI models, cloud storage, and enterprise systems.\n\n**Key Capabilities:**\n- **Workflow Management**: Define workflows as code with version control and automated execution\n- **Task Orchestration**: Chain together API calls, data processing, and AI operations\n- **Real-time Monitoring**: Track execution progress with WebSocket notifications and comprehensive logging\n- **Multi-tenant Architecture**: Organization-scoped resources with role-based access control\n\n**API Versioning and Breaking Changes:**\n\nWe follow a strict compatibility policy to ensure your integrations remain stable:\n\n- **Non-breaking changes** (safe, no action required):\n  - Adding new API endpoints\n  - Adding new optional query parameters to existing endpoints\n  - Adding new fields to API responses\n  - Adding new values to existing enums\n\n- **Breaking changes** (requires client updates):\n  - Removing or renaming API endpoints\n  - Removing query parameters or request fields\n  - Removing response fields\n  - Changing field types or validation rules\n  - Removing values from existing enums\n\n**Client Implementation Requirements:**\n\nYour API clients MUST be designed to gracefully handle additional fields in responses. We may add new fields to any response object without considering this a breaking change. Ensure your JSON parsers ignore unknown fields rather than raising errors.\n\n**Backward Compatibility Guarantee:**\n\nWe commit to maintaining backward compatibility for all non-breaking changes. Breaking changes will be:\n- Announced at least 15 days in advance\n- Documented in our changelog with migration guide\n\nFor the latest API updates and migration guides, see our changelog."
  version: 0.1.0
tags:
- name: service-accounts
  description: Service account operations for managing programmatic API access credentials.
  x-displayName: Service Accounts
paths:
  /api/service-accounts:
    post:
      tags:
      - service-accounts
      summary: Create a new service account
      description: "Create a new service account.\n\nCreates a new service account and returns the full authentication token.\n**Important**: The full token is only shown once during creation. Store it securely.\n\nContext:\n    - This API creates organization-scoped accounts only\n    - Token format: saf_{type}_{org_prefix}_{account_id_prefix}_{random_part}\n\nUse Cases:\n    - Create API integration accounts\n    - Set up automated workflows\n    - Enable programmatic access to platform resources\n\nRelated Endpoints:\n    - GET /service-accounts - List all accounts\n    - GET /service-accounts/{id} - Get account details\n    - PATCH /service-accounts/{id} - Update account"
      operationId: create_service_account_api_service_accounts_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceAccountCreateRequest'
      responses:
        '201':
          description: Service account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccountCreateResponse'
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
    get:
      tags:
      - service-accounts
      summary: List all service accounts
      description: "List all service accounts accessible to the current user.\n\nReturns organization accounts for your organization plus all system accounts.\n\nContext:\n    - Returns accounts from your organization\n    - Includes all system accounts\n    - Does not include accounts from other organizations\n\nRelated Endpoints:\n    - GET /service-accounts/{id} - Get specific account details\n    - POST /service-accounts - Create new account"
      operationId: list_service_accounts_api_service_accounts_get
      parameters:
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of records to skip for pagination
          default: 0
          title: Offset
        description: Number of records to skip for pagination
        example: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Maximum number of records to return
          default: 100
          title: Limit
        description: Maximum number of records to return
        example: 100
      responses:
        '200':
          description: List of service accounts retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceAccountResponse'
                title: Response List Service Accounts Api Service Accounts Get
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/service-accounts/{service_account_id}:
    get:
      tags:
      - service-accounts
      summary: Get a specific service account
      description: "Get details for a specific service account.\n\nReturns service account information including status and token prefix.\nNote: Full token is never returned after creation.\n\nContext:\n    - Users can only access accounts from their organization\n    - System accounts are accessible to all users\n    - Token prefix is shown for identification purposes\n\nRelated Endpoints:\n    - GET /service-accounts - List all accounts\n    - PATCH /service-accounts/{id} - Update account"
      operationId: get_service_account_api_service_accounts__service_account_id__get
      parameters:
      - name: service_account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the service account to retrieve
          title: Service Account Id
        description: UUID of the service account to retrieve
        example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Service account retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccountResponse'
        '403':
          description: Forbidden - User lacks access to this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - The requested resource does not exist
          content:
            application/json:
              examples:
                resource_not_found:
                  summary: Resource not found
                  value:
                    error:
                      message: Resource not found
                      code: not_found
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                flow_not_found:
                  summary: Flow not found
                  value:
                    error:
                      message: Flow not found
                      code: not_found
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
    patch:
      tags:
      - service-accounts
      summary: Update a service account
      description: "Update a service account.\n\nUpdates name and/or description of a service account.\nStatus updates should use activate/deactivate endpoints.\n\nContext:\n    - Can update name and description\n    - Cannot update token (use delete + create for new token)\n    - Cannot update status (use activate/deactivate endpoints)\n\nRelated Endpoints:\n    - POST /service-accounts/{id}/activate - Activate account\n    - POST /service-accounts/{id}/deactivate - Deactivate account"
      operationId: update_service_account_api_service_accounts__service_account_id__patch
      parameters:
      - name: service_account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the service account to update
          title: Service Account Id
        description: UUID of the service account to update
        example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceAccountUpdateRequest'
      responses:
        '200':
          description: Service account updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccountResponse'
        '403':
          description: Forbidden - User lacks access to this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - The requested resource does not exist
          content:
            application/json:
              examples:
                resource_not_found:
                  summary: Resource not found
                  value:
                    error:
                      message: Resource not found
                      code: not_found
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                flow_not_found:
                  summary: Flow not found
                  value:
                    error:
                      message: Flow not found
                      code: not_found
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
    delete:
      tags:
      - service-accounts
      summary: Delete a service account
      description: "Delete a service account.\n\nPermanently deletes a service account. This action cannot be undone.\n\nContext:\n    - Hard delete (permanent removal)\n    - Cannot be undone\n    - Use deactivate if you want to temporarily disable access\n\nRelated Endpoints:\n    - POST /service-accounts/{id}/deactivate - Temporarily disable account"
      operationId: delete_service_account_api_service_accounts__service_account_id__delete
      parameters:
      - name: service_account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the service account to delete
          title: Service Account Id
        description: UUID of the service account to delete
        example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '204':
          description: Service account deleted successfully
        '403':
          description: Forbidden - User lacks access to this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - The requested resource does not exist
          content:
            application/json:
              examples:
                resource_not_found:
                  summary: Resource not found
                  value:
                    error:
                      message: Resource not found
                      code: not_found
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                flow_not_found:
                  summary: Flow not found
                  value:
                    error:
                      message: Flow not found
                      code: not_found
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/service-accounts/{service_account_id}/api-keys:
    get:
      tags:
      - service-accounts
      summary: List API keys for a service account
      description: "List all API keys associated with a specific service account.\n\nReturns all API keys that belong to the specified service account.\nThe user must have access to the service account to view its API keys.\n\nContext:\n    - Only returns API keys for the specified service account\n    - User must have access to the service account\n    - Returns empty list if no API keys exist for the account\n\nRelated Endpoints:\n    - GET /service-accounts/{id} - Get service account details\n    - POST /api-keys - Create a new API key"
      operationId: list_service_account_api_keys_api_service_accounts__service_account_id__api_keys_get
      parameters:
      - name: service_account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the service account to list API keys for
          title: Service Account Id
        description: UUID of the service account to list API keys for
        example: 550e8400-e29b-41d4-a716-446655440000
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of records to skip for pagination
          default: 0
          title: Offset
        description: Number of records to skip for pagination
        example: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Maximum number of records to return
          default: 100
          title: Limit
        description: Maximum number of records to return
        example: 100
      responses:
        '200':
          description: List of API keys retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKeyResponse'
                title: Response List Service Account Api Keys Api Service Accounts  Service Account Id  Api Keys Get
        '403':
          description: Forbidden - User lacks access to this service account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - The requested resource does not exist
          content:
            application/json:
              examples:
                resource_not_found:
                  summary: Resource not found
                  value:
                    error:
                      message: Resource not found
                      code: not_found
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                flow_not_found:
                  summary: Flow not found
                  value:
                    error:
                      message: Flow not found
                      code: not_found
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
    post:
      tags:
      - service-accounts
      summary: Create an API key for a service account
      description: "Create a new API key for a specific service account.\n\nCreates a new API key associated with the specified service account and returns\nthe full authentication token.\n**Important**: The full token is only shown once during creation. Store it securely.\n\nContext:\n    - The user must have access to the service account\n    - System accounts are not visible to API users due to RLS restrictions\n    - All accessible service accounts are organization accounts\n    - Uses 'organization_service_account' identity type\n\nRelated Endpoints:\n    - GET /service-accounts/{id}/api-keys - List API keys for a service account\n    - GET /service-accounts/{id} - Get service account details"
      operationId: create_service_account_api_key_api_service_accounts__service_account_id__api_keys_post
      parameters:
      - name: service_account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the service account to create an API key for
          title: Service Account Id
        description: UUID of the service account to create an API key for
        example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyCreateRequest'
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreateResponse'
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - User lacks access to this service account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - The requested resource does not exist
          content:
            application/json:
              examples:
                resource_not_found:
                  summary: Resource not found
                  value:
                    error:
                      message: Resource not found
                      code: not_found
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                flow_not_found:
                  summary: Flow not found
                  value:
                    error:
                      message: Flow not found
                      code: not_found
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/service-accounts/{service_account_id}/api-keys/{api_key_id}:
    patch:
      tags:
      - service-accounts
      summary: Update an API key
      description: "Update an API key name and/or description.\n\nUpdates the name and/or description of an API key.\nNote: Cannot update the token itself - delete and create a new key for that.\n\nContext:\n    - Can update name and description only\n    - Cannot update token (use delete + create for new token)\n    - User must have access to the API key\n\nRelated Endpoints:\n    - DELETE /service-accounts/{id}/api-keys/{key_id} - Delete API key\n    - GET /service-accounts/{id}/api-keys - List API keys for service account"
      operationId: update_api_key_api_service_accounts__service_account_id__api_keys__api_key_id__patch
      parameters:
      - name: service_account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: UUID of the service account
          title: Service Account Id
        description: UUID of the service account
        ex

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/superai/refs/heads/main/openapi/superai-service-accounts-api-openapi.yml