Composio Connected Accounts API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform Account Management Connected Accounts API
  description: Connected account 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: Connected Accounts
  description: Connected account management
paths:
  /api/v3/connected_accounts:
    get:
      summary: List connected accounts with optional filters
      description: Retrieves all connected accounts for your project. Connected accounts represent authenticated user connections to external services (e.g., a user's Gmail account, Slack workspace). Filter by toolkit, status, user ID, or auth config to find specific connections.
      tags:
      - Connected Accounts
      operationId: getConnectedAccounts
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: array
          nullable: true
          items:
            type: string
          description: The toolkit slugs of the connected accounts
        required: false
        description: The toolkit slugs of the connected accounts
        name: toolkit_slugs
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
            enum:
            - INITIALIZING
            - INITIATED
            - ACTIVE
            - FAILED
            - EXPIRED
            - INACTIVE
            - REVOKED
          description: The status of the connected account
        required: false
        description: The status of the connected account
        name: statuses
        in: query
      - schema:
          type: string
          nullable: true
          description: The cursor to paginate through the connected accounts
        required: false
        description: The cursor to paginate through the connected accounts
        name: cursor
        in: query
      - schema:
          type: number
          nullable: true
          description: The limit of the connected accounts to return
        required: false
        description: The limit of the connected accounts to return
        name: limit
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
          description: The user ids of the connected accounts
        required: false
        description: The user ids of the connected accounts
        name: user_ids
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
            format: authConfigId
          description: The auth config ids of the connected accounts
        required: false
        description: The auth config ids of the connected accounts
        name: auth_config_ids
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
            format: connectedAccountId
          description: The connected account ids to filter by
        required: false
        description: The connected account ids to filter by
        name: connected_account_ids
        in: query
      - schema:
          type: string
          enum:
          - created_at
          - updated_at
          default: created_at
          description: The order by of the connected accounts
        required: false
        description: The order by of the connected accounts
        name: order_by
        in: query
      - schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
          description: The order direction of the connected accounts
        required: false
        description: The order direction of the connected accounts
        name: order_direction
        in: query
      - schema:
          type: string
          enum:
          - PRIVATE
          - SHARED
          - ALL
          description: '[Experimental] Filter by sharing model. Default (omitted) returns PRIVATE only — shared accounts must be requested explicitly. Pass SHARED for only shared accounts, or ALL for PRIVATE + SHARED.'
          x-experimental: true
        required: false
        description: '[Experimental] Filter by sharing model. Default (omitted) returns PRIVATE only — shared accounts must be requested explicitly. Pass SHARED for only shared accounts, or ALL for PRIVATE + SHARED.'
        name: account_type
        in: query
      responses:
        '200':
          description: Successfully retrieved connected accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        toolkit:
                          type: object
                          properties:
                            slug:
                              type: string
                              description: The slug of the toolkit
                          required:
                          - slug
                        auth_config:
                          type: object
                          properties:
                            id:
                              type: string
                              format: authConfigId
                              description: The id of the auth config
                            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 authScheme is part of the connection state use it there
                              deprecated: true
                            is_composio_managed:
                              type: boolean
                              description: Whether the auth config is managed by Composio
                            is_disabled:
                              type: boolean
                              description: Whether the auth config is disabled
                            deprecated:
                              type: object
                              properties:
                                uuid:
                                  type: string
                                  format: uuid
                                  description: The uuid of the auth config
                              required:
                              - uuid
                              deprecated: true
                          required:
                          - id
                          - auth_scheme
                          - is_composio_managed
                          - is_disabled
                        id:
                          type: string
                          format: connectedAccountId
                          description: The id of the connection
                        word_id:
                          type: string
                          nullable: true
                          description: A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., "gmail_red-castle")
                        alias:
                          type: string
                          nullable: true
                          description: A user-defined alias for the connected account
                        user_id:
                          type: string
                          description: This is deprecated, we will not be providing userId from this api anymore, you will only be able to read via userId not get it back
                          deprecated: true
                        status:
                          type: string
                          enum:
                          - INITIALIZING
                          - INITIATED
                          - ACTIVE
                          - FAILED
                          - EXPIRED
                          - INACTIVE
                          - REVOKED
                          description: The status of the connection
                        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
                        created_at:
                          type: string
                          description: The created at of the connection
                        updated_at:
                          type: string
                          description: The updated at of the connection
                        state:
                          oneOf:
                          - type: object
                            properties:
                              authScheme:
                                type: string
                                enum:
                                - OAUTH1
                              val:
                                oneOf:
                                - 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
                                    status:
                                      type: string
                                      enum:
                                      - INITIALIZING
                                  required:
                                  - status
                                  additionalProperties:
                                    nullable: true
                                - 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
                                    status:
                                      type: string
                                      enum:
                                      - INITIATED
                                    oauth_token:
                                      type: string
                                    authUri:
                                      type: string
                                    oauth_token_secret:
                                      type: string
                                    redirectUrl:
                                      type: string
                                    callbackUrl:
                                      type: string
                                  required:
                                  - status
                                  - oauth_token
                                  - authUri
                                  - oauth_token_secret
                                  - redirectUrl
                                  additionalProperties:
                                    nullable: true
                                - 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
                                    status:
                                      type: string
                                      enum:
                                      - ACTIVE
                                    oauth_token:
                                      type: string
                                    oauth_token_secret:
                                      type: string
                                    oauth_verifier:
                                      type: string
                                    consumer_key:
                                      type: string
                                    redirectUrl:
                                      type: string
                                    callback_url:
                                      type: string
                                  required:
                                  - status
                                  - oauth_token
                                  - oauth_token_secret
                                  additionalProperties:
                                    nullable: true
                                - 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
                                    status:
                                      type: string
                                      enum:
                                      - FAILED
                                    error:
                                      type: string
                                    error_description:
                                      type: string
                                  required:
                                  - status
                                  additionalProperties:
                                    nullable: true
                                - 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
                                    status:
                                      type: string
                                      enum:
                                      - EXPIRED
                                    expired_at:
                                      type: string
                                  required:
                                  - status
                                  additionalProperties:
                                    nullable: true
                                - 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
                                    status:
                                      type: string
                                      enum:
                                      - INACTIVE
                                    oauth_token:
                                      type: string
                                    oauth_token_secret:
                                      type: string
                                    oauth_verifier:
                                      type: string
                                    consumer_key:
                                      type: string
                                    redirectUrl:
                                      type: string
                                    callback_url:
                                      type: string
                                  required:
                                  - status
                                  - oauth_token
                                  - oauth_token_secret
                                  additionalProperties:
                                    nullable: true
                            required:
                            - authScheme
                            - val
                          - type: object
                            properties:
                              authScheme:
                                type: string
                                enum:
                                - OAUTH2
                              val:
                                oneOf:
                                - 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
                                    status:
                                      type: string
                                      enum:
        

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