> ## 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 a new connected account

> Initiates a new connection to an external service for a user. For OAuth-based toolkits, this returns a redirect URL to complete authentication. For API key-based toolkits, provide the credentials directly in the request body. Use the `user_id` field to associate the connection with a specific user in your system.

**Deprecated for Composio-managed OAuth:** For Composio-managed auth configs on OAuth1, OAuth2, or DCR_OAUTH schemes, this endpoint is being retired and will start returning `400 BadRequest` on **2026-05-08** for new organizations and **2026-07-03** for all remaining organizations. Migrate those calls to `POST /api/v3/connected_accounts/link`. Custom auth configs and non-OAuth schemes (API key, bearer, basic) continue to be supported here. Responses on the retiring path carry a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) for client-side detection.

**Credential check:** where the toolkit supports it, submitted API key, basic, and bearer credentials are checked against the provider before the connection is stored — no opt-in required. For toolkits with the check enabled, credentials the provider rejects fail the request with `ConnectedAccount_CredentialValidationRejected`. If the provider is unreachable, times out, or returns an error of its own, the connection is created as normal.



## OpenAPI

````yaml /api-reference/openapi-v3.json post /api/v3/connected_accounts
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/connected_accounts:
    post:
      tags:
        - Connected Accounts
      summary: Create a new connected account
      description: >-
        Initiates a new connection to an external service for a user. For
        OAuth-based toolkits, this returns a redirect URL to complete
        authentication. For API key-based toolkits, provide the credentials
        directly in the request body. Use the `user_id` field to associate the
        connection with a specific user in your system.


        **Deprecated for Composio-managed OAuth:** For Composio-managed auth
        configs on OAuth1, OAuth2, or DCR_OAUTH schemes, this endpoint is being
        retired and will start returning `400 BadRequest` on **2026-05-08** for
        new organizations and **2026-07-03** for all remaining organizations.
        Migrate those calls to `POST /api/v3/connected_accounts/link`. Custom
        auth configs and non-OAuth schemes (API key, bearer, basic) continue to
        be supported here. Responses on the retiring path carry a `Deprecation`
        header (RFC 9745) and a `Sunset` header (RFC 8594) for client-side
        detection.


        **Credential check:** where the toolkit supports it, submitted API key,
        basic, and bearer credentials are checked against the provider before
        the connection is stored — no opt-in required. For toolkits with the
        check enabled, credentials the provider rejects fail the request with
        `ConnectedAccount_CredentialValidationRejected`. If the provider is
        unreachable, times out, or returns an error of its own, the connection
        is created as normal.
      operationId: postConnectedAccounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                auth_config:
                  type: object
                  properties:
                    id:
                      type: string
                      format: authConfigId
                      description: >-
                        The auth config id of the app (must be a valid auth
                        config id)
                  required:
                    - id
                connection:
                  type: object
                  properties:
                    state:
                      description: The state of the connected account
                      type: object
                      properties:
                        authScheme:
                          type: string
                          enum:
                            - OAUTH1
                            - OAUTH2
                            - API_KEY
                            - BASIC
                            - BEARER_TOKEN
                            - GOOGLE_SERVICE_ACCOUNT
                            - NO_AUTH
                            - CALCOM_AUTH
                            - BILLCOM_AUTH
                            - BASIC_WITH_JWT
                            - SERVICE_ACCOUNT
                            - SAML
                            - DCR_OAUTH
                            - CIMD_OAUTH
                            - S2S_OAUTH2
                        val:
                          type: object
                          properties:
                            subdomain:
                              type: string
                            your-domain:
                              type: string
                            region:
                              type: string
                            shop:
                              type: string
                            account_url:
                              type: string
                            COMPANYDOMAIN:
                              type: string
                            extension:
                              type: string
                            form_api_base_url:
                              type: string
                            instanceEndpoint:
                              type: string
                            api_url:
                              type: string
                            borneo_dashboard_url:
                              type: string
                            proxy_username:
                              type: string
                            proxy_password:
                              type: string
                            domain:
                              type: string
                            version:
                              type: string
                            dc:
                              type: string
                            site_name:
                              type: string
                            instanceName:
                              type: string
                            account_id:
                              type: string
                            your_server:
                              type: string
                            server_location:
                              type: string
                            base_url:
                              type: string
                            displayName:
                              type: string
                            status:
                              type: string
                              enum:
                                - INITIALIZING
                                - INITIATED
                                - ACTIVE
                                - FAILED
                                - EXPIRED
                                - INACTIVE
                            oauth_token:
                              type: string
                            authUri:
                              type: string
                            oauth_token_secret:
                              type: string
                            redirectUrl:
                              type: string
                            callbackUrl:
                              type: string
                            oauth_verifier:
                              type: string
                            consumer_key:
                              type: string
                            callback_url:
                              type: string
                            error:
                              type: string
                            error_description:
                              type: string
                            expired_at:
                              type: string
                          additionalProperties: true
                          required:
                            - status
                      additionalProperties: true
                      required:
                        - authScheme
                        - val
                    data:
                      type: object
                      additionalProperties: {}
                      description: >-
                        DEPRECATED: This parameter will be removed in a future
                        version. Please use state instead.
                      deprecated: true
                    user_id:
                      type: string
                      default: default
                      description: The user id of the connected account
                    alias:
                      type: string
                      maxLength: 255
                      description: >-
                        A human-readable alias for this connected account. Must
                        be unique per entity and toolkit within the project.
                    callback_url:
                      type: string
                      format: uri
                      description: The URL to redirect to after connection completion
                    redirect_uri:
                      type: string
                      format: uri
                      description: >-
                        DEPRECATED: This parameter will be removed in a future
                        version. Please use callback_url instead.
                      deprecated: true
                    deprecated_is_v1_rerouted:
                      type: boolean
                      default: false
                      description: >-
                        DEPRECATED: This parameter will be removed in a future
                        version.
                      deprecated: true
                    experimental:
                      type: object
                      properties:
                        account_type:
                          type: string
                          enum:
                            - PRIVATE
                            - SHARED
                          description: >-
                            Sharing model for this connected account. PRIVATE
                            (default) is usable only by the owning user_id.
                            SHARED is reachable from a tool-router session ONLY
                            when explicitly pinned in the session config — at
                            most one SHARED connection per toolkit per session.
                            Sessions never use a SHARED connection implicitly.
                            Every use of a SHARED connection must pass the
                            acting user_id, which is checked against its ACL.
                          x-experimental: true
                        acl_config_for_shared:
                          type: object
                          properties:
                            allow_all_users:
                              type: boolean
                              description: >-
                                Wildcard "any user_id in the project" allow
                                toggle. Only valid on SHARED connections.
                            allowed_user_ids:
                              type: array
                              items:
                                type: string
                                minLength: 1
                                maxLength: 256
                              maxItems: 1000
                              description: >-
                                Explicit allow list of user_ids who can use this
                                SHARED connection.
                            not_allowed_user_ids:
                              type: array
                              items:
                                type: string
                                minLength: 1
                                maxLength: 256
                              maxItems: 1000
                              description: >-
                                Explicit deny list. Wins on conflict with
                                allow_all_users and allowed_user_ids.
                          description: >-
                            Access control for SHARED connections. Resolution
                            rule (only fires when caller != creator): user in
                            not_allowed_user_ids → DENY; allow_all_users=true →
                            ALLOW; user in allowed_user_ids → ALLOW; else DENY.
                            Default state (omitted or {}) is deny-by-default —
                            only the creator can use.
                          x-experimental: true
                      description: >-
                        Experimental features - not stable, may be modified or
                        removed in future versions.
                      x-experimental: true
              required:
                - auth_config
                - connection
      responses:
        '201':
          description: Successfully created connected account
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: connectedAccountId
                    description: The id of the connected account
                  connectionData:
                    description: The connection data of the connected account
                    type: object
                    properties:
                      authScheme:
                        type: string
                        enum:
                          - OAUTH1
                          - OAUTH2
                          - API_KEY
                          - BASIC
                          - BEARER_TOKEN
                          - GOOGLE_SERVICE_ACCOUNT
                          - NO_AUTH
                          - CALCOM_AUTH
                          - BILLCOM_AUTH
                          - BASIC_WITH_JWT
                          - SERVICE_ACCOUNT
                          - SAML
                          - DCR_OAUTH
                          - CIMD_OAUTH
                          - S2S_OAUTH2
                      val:
                        type: object
                        properties:
                          subdomain:
                            type: string
                          your-domain:
                            type: string
                          region:
                            type: string
                          shop:
                            type: string
                          account_url:
                            type: string
                          COMPANYDOMAIN:
                            type: string
                          extension:
                            type: string
                          form_api_base_url:
                            type: string
                          instanceEndpoint:
                            type: string
                          api_url:
                            type: string
                          borneo_dashboard_url:
                            type: string
                          proxy_username:
                            type: string
                          proxy_password:
                            type: string
                          domain:
                            type: string
                          version:
                            type: string
                          dc:
                            type: string
                          site_name:
                            type: string
                          instanceName:
                            type: string
                          account_id:
                            type: string
                          your_server:
                            type: string
                          server_location:
                            type: string
                          base_url:
                            type: string
                          displayName:
                            type: string
                          status:
                            type: string
                            enum:
                              - INITIALIZING
                              - INITIATED
                              - ACTIVE
                              - FAILED
                              - EXPIRED
                              - INACTIVE
                          oauth_token:
                            type: string
                          authUri:
                            type: string
                          oauth_token_secret:
                            type: string
                          redirectUrl:
                            type: string
                          callbackUrl:
                            type: string
                          oauth_verifier:
                            type: string
                          consumer_key:
                            type: string
                          callback_url:
                            type: string
                          error:
                            type: string
                          error_description:
                            type: string
                          expired_at:
                            type: string
                        additionalProperties: true
                        required:
                          - status
                    additionalProperties: true
                    required:
                      - authScheme
                      - val
                  status:
                    type: string
                    enum:
                      - INITIALIZING
                      - INITIATED
                      - ACTIVE
                      - FAILED
                      - EXPIRED
                      - INACTIVE
                      - REVOKED
                    description: 'DEPRECATED: This field will be removed in a future version'
                    deprecated: true
                  redirect_url:
                    type: string
                    nullable: true
                    description: 'DEPRECATED: This field will be removed in a future version'
                    deprecated: true
                  redirect_uri:
                    type: string
                    nullable: true
                    description: 'DEPRECATED: This field will be removed in a future version'
                    deprecated: true
                  experimental:
                    type: object
                    properties:
                      account_type:
                        type: string
                        enum:
                          - PRIVATE
                          - SHARED
                        description: >-
                          Sharing model for this connected account. PRIVATE is
                          usable only by the owning user_id. SHARED is reachable
                          from a tool-router session only when explicitly pinned
                          in the session config.
                        x-experimental: true
                      acl_config_for_shared:
                        type: object
                        properties:
                          allow_all_users:
                            type: boolean
                          allowed_user_ids:
                            type: array
                            items:
                              type: string
                          not_allowed_user_ids:
                            type: array
                            items:
                              type: string
                        required:
                          - allow_all_users
                          - allowed_user_ids
                          - not_allowed_user_ids
                        description: >-
                          Access control for SHARED connections. Visible only to
                          the connection creator and project/org API key
                          callers; non-creator cookie callers receive the
                          response without this block.
                        x-experimental: true
                    required:
                      - account_type
                    description: >-
                      Experimental features - not stable, may be modified or
                      removed in future versions.
                    x-experimental: true
                required:
                  - id
                  - connectionData
                  - status
                  - redirect_url
                  - redirect_uri
        '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'
        '422':
          description: >-
            Unprocessable entity. The auth scheme could not be resolved or the
            connected account is in an invalid state for this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    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

````