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

# Update a connected account

> Update a connected account. Supports updating the alias and/or credentials. Only specified fields will be updated. Set a credential field to null to remove it. Alias must be unique within the same project, entity, and toolkit scope.



## OpenAPI

````yaml api-reference/openapi-v3.json PATCH /api/v3/connected_accounts/{nanoid}
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/{nanoid}:
    patch:
      tags:
        - Connected Accounts
      summary: Update a connected account
      description: >-
        Update a connected account. Supports updating the alias and/or
        credentials. Only specified fields will be updated. Set a credential
        field to null to remove it. Alias must be unique within the same
        project, entity, and toolkit scope.
      operationId: patchConnectedAccountsByNanoid
      parameters:
        - schema:
            type: string
            format: connectedAccountId
          required: true
          description: The unique identifier (nanoid) of the connected account
          example: ca_1a2b3c4d5e6f
          name: nanoid
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchConnectedAccountBody'
            examples:
              credentials:
                summary: Update credentials
                value:
                  connection:
                    state:
                      authScheme: BEARER_TOKEN
                      val:
                        token: new_access_token
              alias:
                summary: Update alias
                value:
                  alias: work-gmail
      responses:
        '200':
          description: Successfully updated connected account
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the update was successful
                  id:
                    type: string
                    format: connectedAccountId
                    description: The unique identifier of the updated connected account
                  status:
                    type: string
                    description: >-
                      The current status of the connected account after the
                      update (ACTIVE, EXPIRED, INACTIVE, etc.)
                required:
                  - success
                  - id
                  - status
                example:
                  success: true
                  id: ca_1a2b3c4d5e6f
                  status: ACTIVE
        '400':
          description: Bad request - Invalid nanoid or invalid credential values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Forbidden - Insufficient permissions to update this connected
            account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found - Connected account does not exist or was deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Conflict - Duplicate alias, or a concurrent write holds the
            connection lease; retry the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error - Failed to update connected account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    PatchConnectedAccountBody:
      type: object
      properties:
        alias:
          type: string
          maxLength: 255
          description: >-
            A human-readable alias for this connected account. Pass an empty
            string to clear the alias. Must be unique per entity and toolkit
            within the project.
        connection:
          type: object
          properties:
            state:
              type: object
              properties:
                authScheme:
                  type: string
                  enum:
                    - BEARER_TOKEN
                    - API_KEY
                    - BASIC
                    - BASIC_WITH_JWT
                    - GOOGLE_SERVICE_ACCOUNT
                    - SERVICE_ACCOUNT
                  description: >-
                    The auth scheme of the connected account. Must match the
                    connection's actual auth scheme.
                val:
                  type: object
                  properties:
                    token:
                      type: string
                      nullable: true
                    generic_api_key:
                      type: string
                      nullable: true
                    api_key:
                      type: string
                      nullable: true
                    bearer_token:
                      type: string
                      nullable: true
                    basic_encoded:
                      type: string
                      nullable: true
                    generic_token:
                      type: string
                      nullable: true
                    api_key_prefix:
                      type: string
                      nullable: true
                    generic_secret:
                      type: string
                      nullable: true
                    generic_id:
                      type: string
                      nullable: true
                    user_agent:
                      type: string
                      nullable: true
                    username:
                      type: string
                      nullable: true
                    password:
                      type: string
                      nullable: true
                    credentials_json:
                      type: string
                      nullable: true
                    application_id:
                      type: string
                      nullable: true
                    installation_id:
                      type: string
                      nullable: true
                    private_key:
                      type: string
                      nullable: true
                  additionalProperties: false
                  description: >-
                    Credential fields to update. Only provided fields are
                    changed — omitted fields are preserved. Set a field to null
                    to remove it.
              required:
                - authScheme
                - val
          required:
            - state
        experimental:
          type: object
          properties:
            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
    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

````