> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Update connection

> Update connection properties including credentials. Credentials are encrypted at rest and never returned in API responses.

This endpoint supports credential rotation for infrastructure-as-code workflows. Depending on the connection type, you can update:
- **Password-based connections** (Postgres, MySQL, etc.): Use `passwordUnencrypted` to update the password
- **BigQuery**: Use `passwordUnencrypted` to update the service account JSON
- **Snowflake**: Use `privateKey` to update the RSA private key (PEM format, minimum 2048 bits)

At least one field must be provided in the request body.




## OpenAPI

````yaml /api/openapi.yaml patch /v1/connections/{connectionId}
openapi: 3.1.0
info:
  title: Omni API
  description: >
    The Omni REST API provides programmatic access to your Omni instance for
    managing users, documents, queries, schedules, and more.  
  version: 1.0.0
  contact:
    name: Omni Support
    url: https://docs.omni.co
servers:
  - url: https://{instance}.omniapp.co/api
    description: Production
    variables:
      instance:
        default: blobsrus
        description: Your production Omni instance subdomain
  - url: https://{instance}.playground.exploreomni.dev/api
    description: Playground
    variables:
      instance:
        default: blobsrus
        description: Your playground Omni instance subdomain
security:
  - bearerAuth: []
  - orgApiKey: []
tags:
  - name: AI
    description: AI-powered query generation
  - name: API Tokens
    description: >-
      Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
      grants)
  - name: Connections
    description: Manage database connections
  - name: Connection environments
    description: Manage connection environments database connections
  - name: Content
    description: Unified content retrieval (documents and folders)
  - name: Content migration
    description: Export and import dashboards
  - name: Content validator
    description: Validate content against models and perform find/replace operations
  - name: Dashboard downloads
    description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
  - name: Dashboard filters and controls
    description: Read and update dashboard filter and control default values
  - name: dbt
    description: Manage dbt configuration for connections
  - name: Documents
    description: Create, retrieve, and manage documents
  - name: Document favorites
    description: Favorite and unfavorite documents
  - name: Document labels
    description: Apply and manage labels on documents
  - name: Document permissions
    description: Manage document-level access
  - name: Labels
    description: >
      Manage labels in an organization. Labels can be applied to documents and
      folders to help organize and categorize content.


      **Label types:**

      - **Basic labels**: Can be created and managed by any user

      - **Verified labels**: Indicate curated or officially sanctioned content.
      Admin-only.

      - **Homepage labels**: Appear on the organization homepage. Admin-only.
  - name: Folders
    description: Create and organize content folders
  - name: Folder permissions
    description: Manage folder-level access
  - name: Jobs
    description: Check status of asynchronous jobs
  - name: Models
    description: Create and manage data models
  - name: Model branches
    description: Manage model branches and merge changes
  - name: Model git configuration
    description: Manage git configuration for shared models
  - name: Queries
    description: Execute workbook queries
  - name: Schedules
    description: Create and manage scheduled tasks
  - name: Schedule recipients
    description: Manage schedule recipients
  - name: Schema refresh schedules
    description: Manage automated schema refresh schedules for connections
  - name: Topics
    description: Retrieve topic information from models
  - name: Uploads
    description: Manage file uploads
  - name: Users
    description: Manage users
  - name: User attributes
    description: Manage user attribute definitions
  - name: User groups
    description: Manage user groups
  - name: User model roles
    description: Manage model and connection role assignments for users
  - name: User group model roles
    description: Manage model and connection role assignments for user groups
  - name: Uploads
    description: Manage CSV and spreadsheet uploads
paths:
  /v1/connections/{connectionId}:
    patch:
      tags:
        - Connections
      summary: Update connection
      description: >
        Update connection properties including credentials. Credentials are
        encrypted at rest and never returned in API responses.


        This endpoint supports credential rotation for infrastructure-as-code
        workflows. Depending on the connection type, you can update:

        - **Password-based connections** (Postgres, MySQL, etc.): Use
        `passwordUnencrypted` to update the password

        - **BigQuery**: Use `passwordUnencrypted` to update the service account
        JSON

        - **Snowflake**: Use `privateKey` to update the RSA private key (PEM
        format, minimum 2048 bits)


        At least one field must be provided in the request body.
      operationId: updateConnection
      parameters:
        - name: connectionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Connection ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                passwordUnencrypted:
                  type: string
                  description: >
                    Password or service account JSON for credential rotation.


                    - For **password-based connections** such as Postgres,
                    MySQL, etc. -  Provide the new password as a string

                    - For **BigQuery** - Provide the entire service account JSON
                    file as a string
                  example: new-password-here
                privateKey:
                  type: string
                  description: >
                    **Only applicable to Snowflake connections**. RSA private
                    key in PEM format for Snowflake connections. Must be at
                    least 2048 bits.
                  example: |-
                    -----BEGIN PRIVATE KEY-----
                    MIIEvgIBADANBg...
                baseRole:
                  type: string
                  description: >
                    The default role for users accessing the connection.
                    Available roles include:


                    - `VIEWER` - Can view the model

                    - `QUERIER` - Can view and query the model

                    - `QUERY_TOPICS` - Can query specific topics. Equivalent to
                    **Restricted Querier.**

                    - `MODELER` - Can edit and model the data

                    - `CONNECTION_ADMIN` - Full administrative access to the
                    connection

                    - `NO_ACCESS` - No access to the model

                    - [Custom roles](/administration/users/custom-roles) defined
                    for your organization
                environmentUserAttribute:
                  oneOf:
                    - type: object
                      properties:
                        attributeName:
                          type: string
                          description: >-
                            The name of the user attribute to use for
                            environments
                        defaultValues:
                          type: array
                          items:
                            type: string
                          description: Array of default values for the user attribute
                      required:
                        - attributeName
                        - defaultValues
                    - type: 'null'
                  description: >-
                    Configuration for environment user attributes. Set to `null`
                    to remove environment user attribute settings.
            examples:
              rotatePassword:
                summary: Rotate password (Postgres, MySQL, etc.)
                value:
                  passwordUnencrypted: new-password-here
              rotateBigQueryKey:
                summary: Rotate BigQuery service account key
                value:
                  passwordUnencrypted: >-
                    {"type":"service_account","project_id":"my-gcp-project","private_key_id":"abc123...","private_key":"-----BEGIN
                    PRIVATE KEY-----\nMIIEvgIBA...\n-----END PRIVATE
                    KEY-----\n","client_email":"my-service@my-gcp-project.iam.gserviceaccount.com","client_id":"123456789","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/..."}
              rotateSnowflakeKey:
                summary: Rotate Snowflake keypair
                value:
                  privateKey: |-
                    -----BEGIN PRIVATE KEY-----
                    MIIEvgIBADANBg...
              updateRole:
                summary: Update base role
                value:
                  baseRole: QUERIER
              combinedUpdate:
                summary: Update credentials and role together
                value:
                  passwordUnencrypted: new-password-here
                  baseRole: MODELER
      responses:
        '200':
          description: Connection updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Updated connection credentials.
        '400':
          description: |
            Bad request. Common causes:
            - Empty or invalid request body
            - `privateKey` used with non-Snowflake connection
            - Invalid private key format or insufficient key length
            - Empty private key provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden. User does not have Connection Admin permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - bearerAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: HTTP response code for the error
          example: <response_code>
        message:
          type: string
          description: Detailed error description
          example: <error_reason>
  responses:
    NotFound:
      description: Not Found - Resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded (60 requests/minute)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Can be either an [Organization API
        Key](/api/authentication#organization-api-keys) or [Personal Access
        Token (PAT)](/api/authentication#personal-access-tokens-pat).


        Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
    orgApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Requires an [Organization API
        Key](/api/authentication#organization-api-keys). Personal Access Tokens
        (PATs) are not supported for this endpoint.


        Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`

````