> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create new authentication configuration

> 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.



## OpenAPI

````yaml /api-reference/openapi-v3.json post /api/v3/auth_configs
openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform API
  description: >-
    Composio v3 API — legacy endpoints under /api/v3/. Use v3.1 for new
    integrations.
  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: Composio production API
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: Authentication related endpoints
    x-group: Authentication
  - name: Auth Configs
    description: Authentication configuration management
    x-group: Auth Configs
  - name: Connected Accounts
    description: Connected account management
    x-group: Connected Accounts
  - name: Logs
    description: Logging and monitoring
    x-group: Logs
  - name: OpenAPI
    description: OpenAPI specification management
    x-group: OpenAPI
  - name: Organization
    description: Organization management
    x-group: Organization
  - name: API Keys
    description: API key management
    x-group: API Keys
  - name: Webhooks
    description: Webhook configuration
    x-group: Webhooks
  - name: Webhook Endpoints
    description: >-
      Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts
      to, plus signing secret storage and verification.
    x-group: Webhook Endpoints
  - name: Webhook Subscriptions
    description: >-
      Webhook delivery subscriptions. Outbound URLs Composio posts trigger
      events to, plus signing secret rotation and event-type filters.
    x-group: Webhook Subscriptions
  - name: Team
    description: Team member management
    x-group: Team
  - name: Consumer Skills
    description: Organization-authored Skill management
    x-group: Consumer Skills
  - name: Toolkits
    description: Toolkit and tool management
    x-group: Toolkits
  - name: Tools
    description: Tool execution endpoints
    x-group: Tools
  - name: Triggers
    description: Trigger management and execution
    x-group: Triggers
  - name: Payments
    description: Payment and subscription management
    x-group: Payments
  - name: Billing
    description: Dashboard billing state — usage, subscription, contract (cookie-auth only)
    x-group: Billing
  - name: Compliance
    description: Organization compliance agreements and acceptance state
    x-group: Compliance
  - name: Files
    description: File management
    x-group: Files
  - name: MCP
    description: MCP server management
    x-group: MCP
  - name: MCP Partner
    description: MCP partner management
    x-group: MCP Partner
  - name: Stripe Projects
    description: Stripe Projects provisioning
    x-group: Stripe Projects
  - name: Tool Router
    description: (Labs) Tool router endpoints
    x-group: Sessions (Prev Tool Router)
  - name: Playground
    description: Dashboard playground chat
    x-group: Playground
  - name: Arena
    description: Arena conversations, messages and terms
    x-group: Arena
  - name: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
paths:
  /api/v3/auth_configs:
    post:
      tags:
        - Auth Configs
      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.
      operationId: postAuthConfigs
      requestBody:
        required: true
        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:
                    - $ref: '#/components/schemas/ComposioManagedAuthConfigCreate'
                    - $ref: '#/components/schemas/CustomAuthConfigCreate'
                  discriminator:
                    propertyName: type
                    mapping:
                      use_composio_managed_auth: '#/components/schemas/ComposioManagedAuthConfigCreate'
                      use_custom_auth: '#/components/schemas/CustomAuthConfigCreate'
                  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.
                          DEPRECATED: use [Get required
                          scopes](/reference/api-reference/toolkits/recommendToolkitScopes)
                          to resolve the scopes for the tools you need, then
                          pass those scopes in `credentials.scopes`.
                        deprecated: true
                    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'
      security:
        - ApiKeyAuth: []
        - UserApiKeyAuth: []
components:
  schemas:
    ComposioManagedAuthConfigCreate:
      type: object
      properties:
        type:
          type: string
          enum:
            - use_composio_managed_auth
        name:
          type: string
          maxLength: 255
          description: The name of the integration
        credentials:
          type: object
          properties:
            scopes:
              anyOf:
                - type: string
                - type: array
                  items:
                    type: string
              description: OAuth scopes requested for the managed auth config.
            user_scopes:
              anyOf:
                - type: string
                - type: array
                  items:
                    type: string
              description: >-
                OAuth user-token scopes requested for the managed auth config.
                This is primarily used by Slack OAuth v2.
          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. DEPRECATED: use [Get required
                scopes](/reference/api-reference/toolkits/recommendToolkitScopes)
                to resolve the scopes for the tools you need, then pass those
                scopes in `credentials.scopes`.
              deprecated: true
          description: >-
            DEPRECATED: use [Get required
            scopes](/reference/api-reference/toolkits/recommendToolkitScopes) to
            resolve the scopes for the tools you need, then pass those scopes in
            `credentials.scopes`.
          deprecated: true
        restrict_to_following_tools:
          type: array
          items:
            type: string
          default: []
          description: >-
            List of tool slugs this auth config is restricted to use with.
            DEPRECATED: use [Get required
            scopes](/reference/api-reference/toolkits/recommendToolkitScopes) to
            resolve the scopes for the tools you need, then pass those scopes in
            `credentials.scopes`.
          deprecated: true
        shared_credentials:
          type: object
          additionalProperties: {}
          description: >-
            Shared credentials that will be inherited by all connected accounts
            using this auth config. DEPRECATED: use `shared_connection_fields`
            instead. It takes the same value and behaves the same way.
          deprecated: true
        shared_connection_fields:
          type: object
          additionalProperties: {}
          description: >-
            Connection field values inherited by every connected account created
            under this auth config (for example a region or subdomain).
            Non-secret values pre-fill the hosted Connect Link form; secret
            values are redacted in responses and never sent to the end user.
        is_enabled_for_tool_router:
          type: boolean
          description: Whether this auth config is enabled for tool router
      required:
        - type
    CustomAuthConfigCreate:
      type: object
      properties:
        type:
          type: string
          enum:
            - use_custom_auth
        name:
          type: string
          maxLength: 255
          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
            - CIMD_OAUTH
            - S2S_OAUTH2
        credentials:
          type: object
          properties:
            scopes:
              anyOf:
                - type: string
                - type: array
                  items:
                    type: string
              description: OAuth scopes requested for the custom auth config.
            user_scopes:
              anyOf:
                - type: string
                - type: array
                  items:
                    type: string
              description: >-
                OAuth user-token scopes requested for the custom auth config.
                This is primarily used by Slack OAuth v2.
          default: {}
        sealed_credentials:
          type: object
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 16384
          description: >-
            [EXPERIMENTAL] Client-sealed secret fields to redeem through the
            organization keyring instance (GET /api/v3.1/keyring/transfer_keys).
            The plaintext must not also appear in credentials.
          x-experimental: true
        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: >-
            List of tool slugs this auth config is restricted to use with.
            DEPRECATED: use [Get required
            scopes](/reference/api-reference/toolkits/recommendToolkitScopes) to
            resolve the scopes for the tools you need, then pass those scopes in
            `credentials.scopes`.
          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. DEPRECATED: use [Get required
                scopes](/reference/api-reference/toolkits/recommendToolkitScopes)
                to resolve the scopes for the tools you need, then pass those
                scopes in `credentials.scopes`.
              deprecated: true
          description: >-
            DEPRECATED: use [Get required
            scopes](/reference/api-reference/toolkits/recommendToolkitScopes) to
            resolve the scopes for the tools you need, then pass those scopes in
            `credentials.scopes`.
          deprecated: true
        shared_credentials:
          type: object
          additionalProperties: {}
          description: >-
            Shared credentials that will be inherited by all connected accounts
            using this auth config. DEPRECATED: use `shared_connection_fields`
            instead. It takes the same value and behaves the same way.
          deprecated: true
        shared_connection_fields:
          type: object
          additionalProperties: {}
          description: >-
            Connection field values inherited by every connected account created
            under this auth config (for example a region or subdomain).
            Non-secret values pre-fill the hosted Connect Link form; secret
            values are redacted in responses and never sent to the end user.
        is_enabled_for_tool_router:
          type: boolean
          description: Whether this auth config is enabled for tool router
      required:
        - type
        - authScheme
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
            - message
            - code
            - slug
            - status
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Composio project API key. Create or copy it from the Composio
        dashboard.
      x-default: your-project-api-key
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: x-user-api-key
      description: Your Composio user API key for user-scoped endpoints.
      x-default: your-user-api-key

````