Altimate AI SSO Group Mappings API

openapi: 3.1.0
info:
  title: Fast ACCOUNT_COSTS SSO Group Mappings API
  version: 0.1.0
tags:
- name: SSO Group Mappings
paths:
  /sso-group-mappings/targets:
    get:
      tags:
      - SSO Group Mappings
      summary: List Targets
      description: Return all teams and roles for SSO mapping target dropdowns (no RBAC filtering).
      operationId: list_targets_sso_group_mappings_targets_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
      - HTTPBearer: []
  /sso-group-mappings/config:
    get:
      tags:
      - SSO Group Mappings
      summary: Get Config
      description: Read SSO team sync configuration, returning defaults if not yet configured.
      operationId: get_config_sso_group_mappings_config_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOTeamSyncConfigResponse'
      security:
      - HTTPBearer: []
      - HTTPBearer: []
    put:
      tags:
      - SSO Group Mappings
      summary: Update Config
      description: Create or update SSO team sync configuration.
      operationId: update_config_sso_group_mappings_config_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSOTeamSyncConfigUpdate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOTeamSyncConfigResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
      security:
      - HTTPBearer: []
      - HTTPBearer: []
  /sso-group-mappings/mappings:
    get:
      tags:
      - SSO Group Mappings
      summary: List Mappings
      description: 'Get SSO group mappings with resolved target names and creator emails.


        Pass include_inactive=true to also see deactivated mappings (for reactivation).'
      operationId: list_mappings_sso_group_mappings_mappings_get
      security:
      - HTTPBearer: []
      - HTTPBearer: []
      parameters:
      - name: mapping_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mapping Type
      - name: include_inactive
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Inactive
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SSOGroupMappingResponse'
                title: Response List Mappings Sso Group Mappings Mappings Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - SSO Group Mappings
      summary: Create Mapping
      description: Create a new SSO group mapping with duplicate and target validation.
      operationId: create_mapping_sso_group_mappings_mappings_post
      security:
      - HTTPBearer: []
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSOGroupMappingCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOGroupMappingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sso-group-mappings/mappings/{mapping_id}:
    put:
      tags:
      - SSO Group Mappings
      summary: Update Mapping
      description: Update an existing SSO group mapping.
      operationId: update_mapping_sso_group_mappings_mappings__mapping_id__put
      security:
      - HTTPBearer: []
      - HTTPBearer: []
      parameters:
      - name: mapping_id
        in: path
        required: true
        schema:
          type: integer
          title: Mapping Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSOGroupMappingUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOGroupMappingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - SSO Group Mappings
      summary: Delete Mapping
      description: Soft-delete an SSO group mapping and record an audit event.
      operationId: delete_mapping_sso_group_mappings_mappings__mapping_id__delete
      security:
      - HTTPBearer: []
      - HTTPBearer: []
      parameters:
      - name: mapping_id
        in: path
        required: true
        schema:
          type: integer
          title: Mapping Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sso-group-mappings/preview:
    post:
      tags:
      - SSO Group Mappings
      summary: Preview Mappings
      description: Preview how external SSO groups would resolve to teams and roles.
      operationId: preview_mappings_sso_group_mappings_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSOPreviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOPreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
      security:
      - HTTPBearer: []
      - HTTPBearer: []
  /sso-group-mappings/external-groups:
    get:
      tags:
      - SSO Group Mappings
      summary: List External Groups
      description: List uploaded external SSO groups with optional search filter.
      operationId: list_external_groups_sso_group_mappings_external_groups_get
      security:
      - HTTPBearer: []
      - HTTPBearer: []
      parameters:
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOExternalGroupListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sso-group-mappings/external-groups/upload:
    post:
      tags:
      - SSO Group Mappings
      summary: Upload External Groups
      description: 'Upload a CSV of external SSO group names.


        CSV format: group_name

        Merge strategy: new groups inserted, existing skipped, soft-deleted re-activated.'
      operationId: upload_external_groups_sso_group_mappings_external_groups_upload_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_external_groups_sso_group_mappings_external_groups_upload_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOBulkUploadResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
      security:
      - HTTPBearer: []
      - HTTPBearer: []
  /sso-group-mappings/mappings/upload:
    post:
      tags:
      - SSO Group Mappings
      summary: Upload Mappings
      description: 'Upload a CSV of SSO group mappings for bulk creation.


        CSV format: external_group_identifier,match_type,mapping_type,target_name

        - mapping_type: "team" or "role"

        - target_name: team name (for team mappings) or role title (for role mappings)

        - match_type: exact, prefix, contains, suffix (defaults to "exact")'
      operationId: upload_mappings_sso_group_mappings_mappings_upload_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_mappings_sso_group_mappings_mappings_upload_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOBulkMappingUploadResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
      security:
      - HTTPBearer: []
      - HTTPBearer: []
  /sso-group-mappings/audit-events:
    get:
      tags:
      - SSO Group Mappings
      summary: List Audit Events
      description: Query SSO audit events with optional filters and pagination.
      operationId: list_audit_events_sso_group_mappings_audit_events_get
      security:
      - HTTPBearer: []
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: User Id
      - name: event_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Event Type
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Start Date
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: End Date
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          default: 100
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOAuditEventListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PreviewTeamMatch:
      properties:
        user_group_id:
          type: integer
          title: User Group Id
        source_group:
          type: string
          title: Source Group
      type: object
      required:
      - user_group_id
      - source_group
      title: PreviewTeamMatch
    SSOTeamSyncConfigUpdate:
      properties:
        enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enabled
        provider:
          anyOf:
          - type: string
            enum:
            - azure
            - okta
            - other
          - type: 'null'
          title: Provider
        group_claim_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Group Claim Name
        group_prefix_filter:
          anyOf:
          - type: string
          - type: 'null'
          title: Group Prefix Filter
        enable_graph_api_fallback:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enable Graph Api Fallback
        graph_api_tenant_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Graph Api Tenant Id
        enable_okta_api_fallback:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enable Okta Api Fallback
        okta_domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Okta Domain
      type: object
      title: SSOTeamSyncConfigUpdate
    SSOGroupMappingCreate:
      properties:
        external_group_identifier:
          type: string
          maxLength: 500
          minLength: 1
          title: External Group Identifier
        match_type:
          type: string
          enum:
          - exact
          - prefix
          - contains
          - suffix
          title: Match Type
          default: exact
        mapping_type:
          type: string
          enum:
          - team
          - role
          title: Mapping Type
        target_id:
          type: integer
          title: Target Id
      type: object
      required:
      - external_group_identifier
      - mapping_type
      - target_id
      title: SSOGroupMappingCreate
    BulkUploadFailure:
      properties:
        row:
          type: integer
          title: Row
        reason:
          type: string
          title: Reason
      type: object
      required:
      - row
      - reason
      title: BulkUploadFailure
    SSOPreviewRequest:
      properties:
        external_groups:
          items:
            type: string
          type: array
          maxItems: 200
          minItems: 1
          title: External Groups
      type: object
      required:
      - external_groups
      title: SSOPreviewRequest
    SSOGroupMappingResponse:
      properties:
        id:
          type: integer
          title: Id
        uuid:
          type: string
          format: uuid
          title: Uuid
        external_group_identifier:
          type: string
          title: External Group Identifier
        match_type:
          type: string
          title: Match Type
        mapping_type:
          type: string
          title: Mapping Type
        target_id:
          type: integer
          title: Target Id
        target_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Name
        is_active:
          type: boolean
          title: Is Active
        created_by_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By Email
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - uuid
      - external_group_identifier
      - match_type
      - mapping_type
      - target_id
      - is_active
      - created_at
      - updated_at
      title: SSOGroupMappingResponse
    SSOTeamSyncConfigResponse:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
          default: other
        group_claim_name:
          type: string
          title: Group Claim Name
          default: groups
        group_prefix_filter:
          anyOf:
          - type: string
          - type: 'null'
          title: Group Prefix Filter
        enable_graph_api_fallback:
          type: boolean
          title: Enable Graph Api Fallback
          default: false
        graph_api_tenant_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Graph Api Tenant Id
        enable_okta_api_fallback:
          type: boolean
          title: Enable Okta Api Fallback
          default: false
        okta_domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Okta Domain
      type: object
      title: SSOTeamSyncConfigResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PreviewRoleMatch:
      properties:
        role:
          type: string
          title: Role
        source_group:
          type: string
          title: Source Group
      type: object
      required:
      - role
      - source_group
      title: PreviewRoleMatch
    SSOExternalGroupListResponse:
      properties:
        groups:
          items:
            $ref: '#/components/schemas/SSOExternalGroupResponse'
          type: array
          title: Groups
          default: []
        total:
          type: integer
          title: Total
          default: 0
      type: object
      title: SSOExternalGroupListResponse
    Body_upload_mappings_sso_group_mappings_mappings_upload_post:
      properties:
        file:
          type: string
          format: binary
          title: File
      type: object
      required:
      - file
      title: Body_upload_mappings_sso_group_mappings_mappings_upload_post
    SSOExternalGroupResponse:
      properties:
        id:
          type: integer
          title: Id
        group_name:
          type: string
          title: Group Name
        source:
          type: string
          title: Source
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - group_name
      - source
      - created_at
      title: SSOExternalGroupResponse
    SSOAuditEventResponse:
      properties:
        id:
          type: integer
          title: Id
        tenant:
          type: string
          title: Tenant
        user_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: User Id
        user_email:
          anyOf:
          - type: string
          - type: 'null'
          title: User Email
        event_type:
          type: string
          title: Event Type
        target_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Type
        target_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Target Id
        target_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Name
        old_value:
          anyOf:
          - type: string
          - type: 'null'
          title: Old Value
        new_value:
          anyOf:
          - type: string
          - type: 'null'
          title: New Value
        source:
          type: string
          title: Source
        source_group_identifier:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Group Identifier
        performed_by:
          anyOf:
          - type: integer
          - type: 'null'
          title: Performed By
        performed_by_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Performed By Email
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - tenant
      - event_type
      - source
      - created_at
      title: SSOAuditEventResponse
    SSOPreviewResponse:
      properties:
        team_results:
          items:
            $ref: '#/components/schemas/PreviewTeamMatch'
          type: array
          title: Team Results
          default: []
        role_result:
          anyOf:
          - $ref: '#/components/schemas/PreviewRoleMatch'
          - type: 'null'
        matched_teams:
          type: integer
          title: Matched Teams
          default: 0
        unmatched_count:
          type: integer
          title: Unmatched Count
          default: 0
      type: object
      title: SSOPreviewResponse
    SSOBulkUploadResponse:
      properties:
        total_processed:
          type: integer
          title: Total Processed
          default: 0
        created:
          type: integer
          title: Created
          default: 0
        skipped:
          type: integer
          title: Skipped
          default: 0
        reactivated:
          type: integer
          title: Reactivated
          default: 0
        failures:
          items:
            $ref: '#/components/schemas/BulkUploadFailure'
          type: array
          title: Failures
          default: []
      type: object
      title: SSOBulkUploadResponse
    Body_upload_external_groups_sso_group_mappings_external_groups_upload_post:
      properties:
        file:
          type: string
          format: binary
          title: File
      type: object
      required:
      - file
      title: Body_upload_external_groups_sso_group_mappings_external_groups_upload_post
    SSOGroupMappingUpdate:
      properties:
        external_group_identifier:
          anyOf:
          - type: string
            maxLength: 500
            minLength: 1
          - type: 'null'
          title: External Group Identifier
        match_type:
          anyOf:
          - type: string
            enum:
            - exact
            - prefix
            - contains
            - suffix
          - type: 'null'
          title: Match Type
        target_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Target Id
        is_active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Active
      type: object
      title: SSOGroupMappingUpdate
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SSOAuditEventListResponse:
      properties:
        events:
          items:
            $ref: '#/components/schemas/SSOAuditEventResponse'
          type: array
          title: Events
          default: []
        total:
          type: integer
          title: Total
          default: 0
      type: object
      title: SSOAuditEventListResponse
    SSOBulkMappingUploadResponse:
      properties:
        total_processed:
          type: integer
          title: Total Processed
          default: 0
        created:
          type: integer
          title: Created
          default: 0
        failures:
          items:
            $ref: '#/components/schemas/BulkUploadFailure'
          type: array
          title: Failures
          default: []
      type: object
      title: SSOBulkMappingUploadResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer