> ## 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 auth link session

> Creates a new authentication link session that users can use to connect their accounts



## OpenAPI

````yaml /api-reference/openapi-v3.json post /api/v3/connected_accounts/link
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/link:
    post:
      tags:
        - Connected Accounts
      summary: Create a new auth link session
      description: >-
        Creates a new authentication link session that users can use to connect
        their accounts
      operationId: postConnectedAccountsLink
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth_config_id:
                  type: string
                  format: authConfigId
                  description: The auth config id to create a link for
                user_id:
                  type: string
                  minLength: 1
                  description: The user id to create a link for
                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
                  description: The callback url to create a link for
                connection_data:
                  description: >-
                    Optional data to pre-fill connection fields with default
                    values
                  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
                    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
                    state_prefix:
                      type: string
                      maxLength: 40
                      description: The oauth2 state prefix for the connection
                    long_redirect_url:
                      type: boolean
                      description: Whether to return the redirect url without shortening
                    code_verifier:
                      type: string
                    finalRedirectUri:
                      type: string
                    webhook_signature:
                      type: string
                    access_token:
                      type: string
                    id_token:
                      type: string
                      nullable: true
                    token_type:
                      type: string
                    refresh_token:
                      type: string
                      nullable: true
                    expires_in:
                      anyOf:
                        - type: number
                        - type: string
                        - nullable: true
                          type: object
                    scope:
                      anyOf:
                        - type: string
                        - type: array
                          items:
                            type: string
                        - nullable: true
                          type: object
                    authed_user:
                      type: object
                      properties:
                        access_token:
                          type: string
                        scope:
                          type: string
                      description: for slack user scopes
                    extra_token_data:
                      type: object
                      additionalProperties: {}
                    revoked_at:
                      type: string
                    generic_api_key:
                      type: string
                    api_key:
                      type: string
                    bearer_token:
                      type: string
                    basic_encoded:
                      type: string
                    username:
                      type: string
                    password:
                      type: string
                    token:
                      type: string
                    composio_link_redirect_url:
                      type: string
                    credentials_json:
                      type: string
                    sessionId:
                      type: string
                    devKey:
                      type: string
                    application_id:
                      type: string
                    installation_id:
                      type: string
                    private_key:
                      type: string
                    client_id:
                      type: string
                      description: Dynamically registered client ID
                    client_secret:
                      type: string
                      description: Dynamically registered client secret
                    client_id_issued_at:
                      type: number
                    client_secret_expires_at:
                      type: number
                    expires_at:
                      type: string
                  additionalProperties: 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_id
                - user_id
      responses:
        '201':
          description: Successfully created auth link
          content:
            application/json:
              schema:
                type: object
                properties:
                  link_token:
                    type: string
                    description: The generated link token for the auth session
                  redirect_url:
                    type: string
                    description: The redirect URI to send users to for authentication
                  expires_at:
                    type: string
                    description: ISO timestamp when the link expires
                  connected_account_id:
                    type: string
                    format: connectedAccountId
                    description: The connected account ID that was created
                  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:
                  - link_token
                  - redirect_url
                  - expires_at
                  - connected_account_id
        '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: Auth config not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          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: []
        - UserApiKeyAuth: []
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
    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

````