Composio Auth Configs API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform Account Management Auth Configs API
  description: Authentication configuration management
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
- url: https://backend.composio.dev
  description: PRODUCTION API
tags:
- name: Auth Configs
  description: Authentication configuration management
paths:
  /api/v3/auth_configs:
    post:
      summary: Create new authentication configuration
      description: Creates a new auth config for a toolkit, allowing you to use your own OAuth credentials or API keys instead of Composio-managed authentication. This is required when you want to use custom OAuth apps (bring your own client ID/secret) or configure specific authentication parameters for a toolkit.
      tags:
      - Auth Configs
      operationId: postAuthConfigs
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                toolkit:
                  type: object
                  properties:
                    slug:
                      type: string
                      description: Toolkit slug to create auth config for
                  required:
                  - slug
                auth_config:
                  oneOf:
                  - type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - use_composio_managed_auth
                      name:
                        type: string
                        description: The name of the integration
                      credentials:
                        type: object
                        properties:
                          scopes:
                            anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                          user_scopes:
                            anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                        default: {}
                      tool_access_config:
                        type: object
                        properties:
                          tools_for_connected_account_creation:
                            type: array
                            items:
                              type: string
                            default: []
                            description: Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes.
                      restrict_to_following_tools:
                        type: array
                        items:
                          type: string
                        default: []
                        description: Use tool_access_config instead. This field will be deprecated in the future.
                        deprecated: true
                      shared_credentials:
                        type: object
                        additionalProperties:
                          nullable: true
                        description: '[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config'
                        x-experimental: true
                      is_enabled_for_tool_router:
                        type: boolean
                        description: Whether this auth config is enabled for tool router
                    required:
                    - type
                  - type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - use_custom_auth
                      name:
                        type: string
                        description: The name of the integration
                      authScheme:
                        type: string
                        enum:
                        - OAUTH2
                        - OAUTH1
                        - API_KEY
                        - BASIC
                        - BILLCOM_AUTH
                        - BEARER_TOKEN
                        - GOOGLE_SERVICE_ACCOUNT
                        - NO_AUTH
                        - BASIC_WITH_JWT
                        - CALCOM_AUTH
                        - SERVICE_ACCOUNT
                        - SAML
                        - DCR_OAUTH
                        - S2S_OAUTH2
                      credentials:
                        type: object
                        properties:
                          scopes:
                            anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                          user_scopes:
                            anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                        default: {}
                      proxy_config:
                        type: object
                        nullable: true
                        properties:
                          proxy_url:
                            type: string
                            format: uri
                            description: The url of the auth proxy
                          proxy_auth_key:
                            type: string
                            description: The auth key for the auth proxy
                        required:
                        - proxy_url
                      restrict_to_following_tools:
                        type: array
                        items:
                          type: string
                        default: []
                        description: Use tool_access_config instead. This field will be deprecated in the future.
                        deprecated: true
                      tool_access_config:
                        type: object
                        properties:
                          tools_for_connected_account_creation:
                            type: array
                            items:
                              type: string
                            default: []
                            description: Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes.
                      shared_credentials:
                        type: object
                        additionalProperties:
                          nullable: true
                        description: '[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config'
                        x-experimental: true
                      is_enabled_for_tool_router:
                        type: boolean
                        description: Whether this auth config is enabled for tool router
                    required:
                    - type
                    - authScheme
                  default:
                    type: use_composio_managed_auth
                    credentials: {}
                    restrict_to_following_tools: []
              required:
              - toolkit
      responses:
        '201':
          description: Successfully created auth config
          content:
            application/json:
              schema:
                type: object
                properties:
                  toolkit:
                    type: object
                    properties:
                      slug:
                        type: string
                        description: The unique key of the toolkit
                    required:
                    - slug
                  auth_config:
                    type: object
                    properties:
                      id:
                        type: string
                        format: authConfigId
                        description: The auth config id of the toolkit (must be a valid auth config id)
                      auth_scheme:
                        type: string
                        description: The authentication mode of the toolkit
                      is_composio_managed:
                        type: boolean
                        description: Whether the auth config is managed by Composio
                      restrict_to_following_tools:
                        type: array
                        items:
                          type: string
                        default: []
                        description: The tools that the user can use with the auth config
                    required:
                    - id
                    - auth_scheme
                    - is_composio_managed
                required:
                - toolkit
                - auth_config
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List authentication configurations with optional filters
      description: Retrieves all auth configs for your project. Auth configs define how users authenticate with external services (OAuth, API keys, etc.). Use filters to find configs for specific toolkits or to distinguish between Composio-managed and custom configurations.
      tags:
      - Auth Configs
      operationId: getAuthConfigs
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          anyOf:
          - type: string
          - type: boolean
          description: Whether to filter by composio managed auth configs
        required: false
        description: Whether to filter by composio managed auth configs
        name: is_composio_managed
        in: query
      - schema:
          type: string
        required: false
        description: Comma-separated list of toolkit slugs to filter auth configs by
        in: query
        name: toolkit_slug
      - schema:
          type: string
          description: 'DEPRECATED: This parameter will be removed in a future version. Please use toolkit_slug instead.'
          deprecated: true
        required: false
        description: The app id to filter by
        name: deprecated_app_id
        in: query
      - schema:
          type: string
          description: 'DEPRECATED: This parameter will be removed in a future version.'
          deprecated: true
        required: false
        name: deprecated_status
        in: query
      - schema:
          type: boolean
          nullable: true
          default: false
          description: Show disabled auth configs
        required: false
        description: Show disabled auth configs
        name: show_disabled
        in: query
      - schema:
          type: string
          description: Search auth configs by name or id
        required: false
        description: Search auth configs by name or id
        name: search
        in: query
      - schema:
          type: number
          nullable: true
        required: false
        description: Number of items per page, max allowed is 1000
        name: limit
        in: query
      - schema:
          type: string
        required: false
        description: Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.
        name: cursor
        in: query
      responses:
        '200':
          description: Successfully fetched auth configs
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: authConfigId
                          description: The unique ID of the authentication configuration
                        uuid:
                          type: string
                          description: The UUID of the authentication configuration (for backward compatibility)
                        type:
                          type: string
                          enum:
                          - default
                          - custom
                          description: The type of the authentication configuration (custom or default)
                        toolkit:
                          type: object
                          properties:
                            slug:
                              type: string
                              description: The unique identifier of the integration app
                            logo:
                              type: string
                              description: The URL to the integration app's logo image
                            auth_guide_url:
                              type: string
                              nullable: true
                              description: URL to a guide page with authentication setup instructions
                            auth_hint_url:
                              type: string
                              nullable: true
                              description: URL to a page where users can obtain or configure credentials
                          required:
                          - slug
                          - logo
                          description: Information about the associated integration
                        name:
                          type: string
                          description: The display name of the authentication configuration
                        auth_scheme:
                          type: string
                          enum:
                          - OAUTH2
                          - OAUTH1
                          - API_KEY
                          - BASIC
                          - BILLCOM_AUTH
                          - BEARER_TOKEN
                          - GOOGLE_SERVICE_ACCOUNT
                          - NO_AUTH
                          - BASIC_WITH_JWT
                          - CALCOM_AUTH
                          - SERVICE_ACCOUNT
                          - SAML
                          - DCR_OAUTH
                          - S2S_OAUTH2
                          description: The authentication scheme used (e.g., OAuth2, API Key, etc.)
                        is_composio_managed:
                          type: boolean
                          description: Whether this authentication configuration is managed by Composio or the user
                        credentials:
                          type: object
                          additionalProperties:
                            nullable: true
                          description: The authentication credentials (tokens, keys, etc.) - may be partially hidden for security
                        proxy_config:
                          type: object
                          nullable: true
                          properties:
                            proxy_url:
                              type: string
                              format: uri
                              description: The url of the auth proxy
                            proxy_auth_key:
                              type: string
                              description: The auth key for the auth proxy
                          required:
                          - proxy_url
                        status:
                          type: string
                          enum:
                          - ENABLED
                          - DISABLED
                          description: Current status of the authentication configuration
                        created_by:
                          type: string
                          description: The identifier of the user who created the auth config
                        created_at:
                          type: string
                          description: ISO 8601 date-time when the auth config was created
                        last_updated_at:
                          type: string
                          description: ISO 8601 date-time when the auth config was last updated
                        no_of_connections:
                          type: number
                          description: The number of active connections using this auth config
                        expected_input_fields:
                          type: array
                          items:
                            nullable: true
                          description: Fields expected during connection initialization
                        restrict_to_following_tools:
                          type: array
                          items:
                            type: string
                          description: Use tool_access_config instead. This field will be deprecated in the future.
                          deprecated: true
                        tool_access_config:
                          type: object
                          properties:
                            tools_for_connected_account_creation:
                              type: array
                              items:
                                type: string
                              default: []
                              description: Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes.
                            tools_available_for_execution:
                              type: array
                              items:
                                type: string
                              default: []
                              description: The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config.
                        shared_credentials:
                          type: object
                          additionalProperties:
                            nullable: true
                          description: '[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config'
                          x-experimental: true
                        is_enabled_for_tool_router:
                          type: boolean
                          description: Whether this auth config is enabled for tool router
                        deprecated_params:
                          type: object
                          properties:
                            default_connector_id:
                              type: string
                              nullable: true
                              description: 'Deprecated: Default connector ID'
                            member_uuid:
                              type: string
                              description: 'Deprecated: Member UUID'
                            toolkit_id:
                              type: string
                              description: 'Deprecated: Toolkit ID'
                            expected_input_fields:
                              type: array
                              items:
                                type: object
                                additionalProperties:
                                  nullable: true
                              description: 'Deprecated: Fields expected during connection initialization'
                          required:
                          - default_connector_id
                          description: 'DEPRECATED: This parameter will be removed in a future version.'
                          deprecated: true
                      required:
                      - id
                      - uuid
                      - type
                      - toolkit
                      - name
                      - status
                      - no_of_connections
                      - tool_access_config
                  next_cursor:
                    type: string
                    nullable: true
                  total_pages:
                    type: number
                  current_page:
                    type: number
                  total_items:
                    type: number
                required:
                - items
                - total_pages
                - current_page
                - total_items
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/auth_configs/{nanoid}:
    get:
      summary: Get single authentication configuration by ID
      description: Retrieves detailed information about a specific authentication configuration using its unique identifier.
      tags:
      - Auth Configs
      operationId: getAuthConfigsByNanoid
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          format: authConfigId
          description: The unique identifier of the authentication configuration to retrieve
        required: true
        description: The unique identifier of the authentication configuration to retrieve
        name: nanoid
        in: path
      responses:
        '200':
          description: Successfully fetched auth config
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: authConfigId
                    description: The unique ID of the authentication configuration
                  uuid:
                    type: string
                    description: The UUID of the authentication configuration (for backward compatibility)
                  type:
                    type: string
                    enum:
                    - default
                    - custom
                    description: The type of the authentication configuration (custom or default)
                  toolkit:
                    type: object
                    properties:
                      slug:
                        type: string
                        description: The unique identifier of the integration app
                      logo:
                        type: string
                        description: The URL to the integration app's logo image
                      auth_guide_url:
                        type: string
                        nullable: true
                        description: URL to a guide page with authentication setup instructions
                      auth_hint_url:
                        type: string
                        nullable: true
                        description: URL to a page where users can obtain or configure credentials
                    required:
                    - slug
                    - logo
                    description: Information about the associated integration
                  name:
                    type: string
                    description: The display name of the authentication configuration
                  auth_scheme:
                    type: string
                    enum:
                    - OAUTH2
                    - OAUTH1
                    - API_KEY
                    - BASIC
                    - BILLCOM_AUTH
                    - BEARER_TOKEN
                    - GOOGLE_SERVICE_ACCOUNT
                    - NO_AUTH
                    - BASIC_WITH_JWT
                    - CALCOM_AUTH
                    - SERVICE_ACCOUNT
                    - SAML
                    - DCR_OAUTH
                    - S2S_OAUTH2
                    description: The authentication scheme used (e.g., OAuth2, API Key, etc.)
                  is_composio_managed:
                    type: boolean
                    description: Whether this authentication configuration is managed by Composio or the user
                  credentials:
                    type: object
                    additionalProperties:
                      nullable: true
                    description: The authentication credentials (tokens, keys, etc.) - may be partially hidden for security
                  proxy_config:
                    type: object
                    nullable: true
                    properties:
                      proxy_url:
                        type: string
                        format: uri
                        description: The url of the auth proxy
                      proxy_auth_key:
                        type: string
                        description: The auth key for the auth proxy
                    required:
                    - proxy_url
                  status:
                    type: string
                    enum:
                    - ENABLED
                    - DISABLED
                    description: Current status of the authentication configuration
                  created_by:
                    type: string
                    description: The identifier of the user who created the auth config
                  created_at:
                    type: string
                    description: ISO 8601 date-time when the auth config was created
                  last_updated_at:
                    type: string
                    description: ISO 8601 date-time when the auth config was last updated
                  no_of_connections:
                    type: number
                    description: The number of active connections using this auth config
                  expected_input_fields:
                    type: array
                    items:
                      nullable: true
                    description: Fields expected during connection initialization
                  restrict_to_following_tools:
                    type: array
                    items:
                      type: string
                    description: Use tool_access_config instead. This field will be deprecated in the future.
                    deprecated: true
                  tool_access_config:
                    type: object
                    properties:
                      tools_for_connected_account_creation:
                        type: array
                        items:
                          type: string
                        default: []
                        description: Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes.
                      tools_available_for_execution:
                        type: array
                        items:
                          type: string
                        default: []
                        description: The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config.
                  shared_credentials:
                    type: object
                    additionalProperties:
                      nullable: true
                    description: '[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config'
                    x-experimental: true
                  is_enabled_for_tool_router:
                    type: boolean
                    description: Whether this auth config is enabled for tool router
                  deprecated_params:
                    type: object
                    properties:
                      default_connector_id:
                        type: string
                        nullable: true
                        description: 'Deprecated: Default connector ID'
                      member_uuid:
                        type: string
                        description: 'Deprecated: Member UUID'
                      toolkit_id:
                        type: string
                        description: 'Deprecated: Toolkit ID'
                      expected_input_fields:
                        type: array
                        items:
                          type: object
                          additionalProperties:
                            nullable: true
                        description: 'Deprecated: Fields expected during connection initialization'
                    required:
                    - default_connector_id
                    description: 'DEPRECATED: This parameter will be removed in a future version.'
                    deprecated: true
                required:
                - id
                - uuid
                - type
                - toolkit
                - name
                - status
                - no_of_connections
                - tool_access_config
        '400':
          description: Bad request - Invalid auth config ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found - Auth configuration does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error - Something went wrong on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      summary: Update an authentication configuration
      description: Modifies an existing authentication configuration with new credentials or other settings. Only specified fields will be updated.
      tags:
      - Auth Configs
      operationId: patchAuthConfigsByNanoid
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          format: authConfigId
          description: The unique identifier of the authentication configuration to update
        required: true
        description: The unique identifier of the authentication configuration to update
        name: nanoid
        in: path
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                    - custom
                  name:
                    type: string
                    minLength: 1
                    description: The display name of the au

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/composio/refs/heads/main/openapi/composio-auth-configs-api-openapi.yml