APIClaw SSO Settings API

openapi: 3.2.0
info:
  title: LiteLLM SSO Settings API
  description: 'Proxy Server to call 100+ LLMs in the OpenAI format. **Customize Swagger Docs**


    👉 ```LiteLLM Admin Panel on /ui```. Create, Edit Keys with SSO. Having issues? Try ```Fallback Login```


    💸 ```LiteLLM Model Cost Map```.


    🔎 ```LiteLLM Model Hub```. See available models on the proxy. **Docs**'
  version: 1.102.1
tags:
- name: SSO Settings
paths:
  /get/internal_user_settings:
    get:
      tags:
      - SSO Settings
      summary: Get Internal User Settings
      description: 'Get all SSO settings from the litellm_settings configuration.

        Returns a structured object with values and descriptions for UI display.'
      operationId: get_internal_user_settings_get_internal_user_settings_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalUserSettingsResponse'
      security:
      - APIKeyHeader: []
  /get/default_team_settings:
    get:
      tags:
      - SSO Settings
      summary: Get Default Team Settings
      description: 'Get the default team parameters (litellm_settings.default_team_params).

        Returns a structured object with values and descriptions for UI display.'
      operationId: get_default_team_settings_get_default_team_settings_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultTeamSettingsResponse'
      security:
      - APIKeyHeader: []
  /update/internal_user_settings:
    patch:
      tags:
      - SSO Settings
      summary: Update Internal User Settings
      description: 'Update the default internal user parameters for SSO users.

        These settings will be applied to new users who sign in via SSO.'
      operationId: update_internal_user_settings_update_internal_user_settings_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DefaultInternalUserParams'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /update/default_team_settings:
    patch:
      tags:
      - SSO Settings
      summary: Update Default Team Settings
      description: 'Update the default team parameters (litellm_settings.default_team_params).

        Applied to every new team for fields not explicitly provided in the create request;

        `models` only applies to teams automatically created via SSO Groups.'
      operationId: update_default_team_settings_update_default_team_settings_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DefaultTeamSSOParams'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /get/sso_settings:
    get:
      tags:
      - SSO Settings
      summary: Get Sso Settings
      description: 'Get all SSO configuration settings from the dedicated SSO table.

        Returns a structured object with values and descriptions for UI display.'
      operationId: get_sso_settings_get_sso_settings_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOSettingsResponse'
      security:
      - APIKeyHeader: []
  /update/sso_settings:
    patch:
      tags:
      - SSO Settings
      summary: Update Sso Settings
      description: Update SSO configuration by saving to the dedicated SSO table.
      operationId: update_sso_settings_update_sso_settings_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSOConfig'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
components:
  schemas:
    DefaultInternalUserParams:
      properties:
        user_role:
          anyOf:
          - type: string
            enum:
            - proxy_admin
            - proxy_admin_viewer
            - internal_user
            - internal_user_viewer
          - type: 'null'
          title: User Role
          description: Default role assigned to new users created
          default: internal_user_viewer
        max_budget:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Budget
          description: Default maximum budget (in USD) for new users created
        budget_duration:
          anyOf:
          - type: string
          - type: 'null'
          title: Budget Duration
          description: Default budget duration for new users (e.g. 'daily', 'weekly', 'monthly')
        models:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Models
          description: Default list of models that new users can access
        teams:
          anyOf:
          - items:
              type: string
            type: array
          - items:
              $ref: '#/components/schemas/NewUserRequestTeam'
            type: array
          - type: 'null'
          title: Teams
          description: Default teams for new users created
      type: object
      title: DefaultInternalUserParams
      description: Default parameters to apply when a new user signs in via SSO or is created on the /user/new API endpoint
    InternalUserSettingsResponse:
      properties:
        values:
          additionalProperties: true
          type: object
          title: Values
        field_schema:
          additionalProperties: true
          type: object
          title: Field Schema
      type: object
      required:
      - values
      - field_schema
      title: InternalUserSettingsResponse
      description: Response model for internal user settings
    AccessControl_UI_AccessMode:
      properties:
        type:
          type: string
          const: restricted_sso_group
          title: Type
        restricted_sso_group:
          type: string
          title: Restricted Sso Group
        sso_group_jwt_field:
          type: string
          title: Sso Group Jwt Field
      type: object
      required:
      - type
      - restricted_sso_group
      - sso_group_jwt_field
      title: AccessControl_UI_AccessMode
      description: Model for Controlling UI Access Mode via SSO Groups
    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
    SSOSettingsResponse:
      properties:
        values:
          additionalProperties: true
          type: object
          title: Values
        field_schema:
          additionalProperties: true
          type: object
          title: Field Schema
        provenance:
          additionalProperties:
            type: string
          type: object
          title: Provenance
      type: object
      required:
      - values
      - field_schema
      title: SSOSettingsResponse
      description: Response model for SSO settings
    TeamMappings:
      properties:
        team_ids_jwt_field:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Ids Jwt Field
          description: The field name in the SSO/JWT token that contains the team IDs array (e.g., 'groups', 'teams'). Supports dot notation for nested fields.
      type: object
      title: TeamMappings
      description: 'Configuration for mapping SSO JWT fields to team IDs.


        This allows configuring team_ids_jwt_field via the database instead of

        requiring config file changes and restarts.'
    NewUserRequestTeam:
      properties:
        team_id:
          type: string
          title: Team Id
        max_budget_in_team:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Budget In Team
        user_role:
          type: string
          enum:
          - user
          - admin
          title: User Role
          default: user
      type: object
      required:
      - team_id
      title: NewUserRequestTeam
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DefaultTeamSettingsResponse:
      properties:
        values:
          additionalProperties: true
          type: object
          title: Values
        field_schema:
          additionalProperties: true
          type: object
          title: Field Schema
      type: object
      required:
      - values
      - field_schema
      title: DefaultTeamSettingsResponse
      description: Response model for default team settings
    SSOConfig:
      properties:
        google_client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Google Client Id
          description: Google OAuth Client ID for SSO authentication
        google_client_secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Google Client Secret
          description: Google OAuth Client Secret for SSO authentication
        microsoft_client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Microsoft Client Id
          description: Microsoft OAuth Client ID for SSO authentication
        microsoft_client_secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Microsoft Client Secret
          description: Microsoft OAuth Client Secret for SSO authentication
        microsoft_tenant:
          anyOf:
          - type: string
          - type: 'null'
          title: Microsoft Tenant
          description: Microsoft Azure Tenant ID for SSO authentication
        generic_client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Generic Client Id
          description: Generic OAuth Client ID for SSO authentication (used for Okta and other providers)
        generic_client_secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Generic Client Secret
          description: Generic OAuth Client Secret for SSO authentication
        generic_authorization_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Generic Authorization Endpoint
          description: Authorization endpoint URL for generic OAuth provider
        generic_token_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Generic Token Endpoint
          description: Token endpoint URL for generic OAuth provider
        generic_userinfo_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Generic Userinfo Endpoint
          description: User info endpoint URL for generic OAuth provider
        generic_scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Generic Scope
          description: Space-separated OAuth scopes requested from the generic provider, e.g. 'openid email profile'
        saml_idp_metadata_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Saml Idp Metadata Url
          description: URL of the SAML IdP metadata to fetch and parse for SSO authentication
        saml_idp_metadata_xml:
          anyOf:
          - type: string
          - type: 'null'
          title: Saml Idp Metadata Xml
          description: Inline SAML IdP metadata XML, used when a metadata URL is not available
        saml_sp_entity_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Saml Sp Entity Id
          description: SAML Service Provider entityID; defaults to the proxy's /sso/saml/metadata URL
        saml_allow_unsolicited:
          anyOf:
          - type: string
          - type: 'null'
          title: Saml Allow Unsolicited
          description: '''true'' to accept IdP-initiated (unsolicited) SAML responses, which cannot be browser-bound against login CSRF'
        proxy_base_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Proxy Base Url
          description: Base URL of the proxy server for SSO redirects
        user_email:
          anyOf:
          - type: string
          - type: 'null'
          title: User Email
          description: Email of the proxy admin user
        ui_access_mode:
          anyOf:
          - $ref: '#/components/schemas/AccessControl_UI_AccessMode'
          - type: string
          - type: 'null'
          title: Ui Access Mode
          description: Access mode for the UI
        role_mappings:
          anyOf:
          - $ref: '#/components/schemas/RoleMappings'
          - type: 'null'
          description: Configuration for mapping SSO groups to LiteLLM roles based on group claims in the SSO token
        team_mappings:
          anyOf:
          - $ref: '#/components/schemas/TeamMappings'
          - type: 'null'
          description: Configuration for mapping SSO JWT fields to team IDs. Takes precedence over config file settings.
      type: object
      title: SSOConfig
      description: Configuration for SSO environment variables and settings
    KeyManagementRoutes:
      type: string
      enum:
      - /key/generate
      - /key/update
      - /key/delete
      - /key/regenerate
      - /key/service-account/generate
      - /key/{key_id}/regenerate
      - /key/block
      - /key/unblock
      - /key/bulk_update
      - /team/key/bulk_update
      - /key/{key_id}/reset_spend
      - /key/access_group_assignment
      - /auto_router/manage
      - /key/info
      - /key/health
      - /key/list
      - /key/aliases
      - /team/daily/activity
      - /team/daily/activity/aggregated
      - /spend/logs
      - /spend/logs/v2
      title: KeyManagementRoutes
      description: Enum for key management routes
    LitellmUserRoles:
      type: string
      enum:
      - proxy_admin
      - proxy_admin_viewer
      - org_admin
      - internal_user
      - internal_user_viewer
      - team
      - customer
      title: LitellmUserRoles
      description: 'Admin Roles:

        PROXY_ADMIN: admin over the platform

        PROXY_ADMIN_VIEW_ONLY: can login, view all own keys, view all spend

        ORG_ADMIN: admin over a specific organization, can create teams, users only within their organization


        Internal User Roles:

        INTERNAL_USER: can login, view/create/delete their own keys, view their spend

        INTERNAL_USER_VIEW_ONLY: can login, view their own keys, view their own spend



        Team Roles:

        TEAM: used for JWT auth



        Customer Roles:

        CUSTOMER: External users -> these are customers'
    DefaultTeamSSOParams:
      properties:
        models:
          items:
            type: string
          type: array
          title: Models
          description: Default list of models for teams automatically created via SSO Groups
          default: []
        max_budget:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Budget
          description: Default maximum budget (in USD) for new teams, when not explicitly provided
        budget_duration:
          anyOf:
          - type: string
          - type: 'null'
          title: Budget Duration
          description: Default budget duration for new teams, when not explicitly provided (e.g. '24h', '7d', '30d')
        tpm_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tpm Limit
          description: Default tpm limit for new teams, when not explicitly provided
        rpm_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rpm Limit
          description: Default rpm limit for new teams, when not explicitly provided
        team_member_permissions:
          anyOf:
          - items:
              $ref: '#/components/schemas/KeyManagementRoutes'
            type: array
          - type: 'null'
          title: Team Member Permissions
          description: Default permissions granted to members of newly created teams (e.g. /key/generate, /key/update, /key/delete). /key/info and /key/health are always included.
        organization_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Organization Id
          description: Default organization for new teams created without an explicit organization
      type: object
      title: DefaultTeamSSOParams
      description: 'Default parameters applied to every /team/new call for fields not explicitly provided in the request.

        `models` is the exception: it only applies to teams automatically created by LiteLLM via SSO Groups.'
    RoleMappings:
      properties:
        provider:
          type: string
          title: Provider
          description: SSO Provider name (e.g., 'google', 'microsoft', 'generic')
        group_claim:
          type: string
          title: Group Claim
          description: The field name in the SSO token that contains the groups array (e.g., 'groups', 'roles')
        default_role:
          anyOf:
          - $ref: '#/components/schemas/LitellmUserRoles'
          - type: 'null'
          description: Default role to assign if user's groups don't match any role mappings. Must be a valid LitellmUserRoles value (e.g., 'proxy_admin', 'internal_user', 'proxy_admin_viewer')
        roles:
          additionalProperties:
            items:
              type: string
            type: array
          propertyNames:
            $ref: '#/components/schemas/LitellmUserRoles'
          type: object
          title: Roles
          description: 'Mapping of LiteLLM role names to arrays of SSO group names. Example: {''proxy_admin'': [''group-1'', ''group-2''], ''proxy_admin_viewer'': [''group-3'']}'
      type: object
      required:
      - provider
      - group_claim
      title: RoleMappings
      description: 'Configuration for mapping SSO groups to LiteLLM roles.


        The system will look at the group_claim field in the SSO token to determine

        which role to assign the user based on the roles mapping.'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Bearer token
      in: header
      name: x-litellm-api-key