> ## Documentation Index > Fetch the complete documentation index at: https://docs.withampersand.com/llms.txt > Use this file to discover all available pages before exploring further. # Update a connection. > Rotate credentials or update metadata (such as the provider workspace reference) for an existing connection. ## OpenAPI ````yaml platform patch /projects/{projectIdOrName}/connections/{connectionId} openapi: 3.0.1 info: title: Ampersand public API version: 1.0.0 servers: - url: https://api.withampersand.com/v1 security: - APIKeyHeader: [] - Bearer: [] paths: /projects/{projectIdOrName}/connections/{connectionId}: patch: tags: - Connection summary: Update a connection. description: >- Rotate credentials or update metadata (such as the provider workspace reference) for an existing connection. operationId: updateConnection parameters: - name: projectIdOrName in: path required: true description: The Ampersand project ID or project name. schema: type: string example: my-project - name: connectionId in: path required: true schema: type: string description: >- The ID of the connection to update. You can find this via the [list connections endpoint](https://docs.withampersand.com/reference/connection/list-connections). example: connection-123 requestBody: required: true content: application/json: schema: title: Update Connection Request description: >- Specify which fields to update in `updateMask` and provide corresponding values in `connection`. Fields in `connection` not listed in `updateMask` are ignored. type: object required: - updateMask - connection properties: updateMask: type: array items: type: string enum: - providerWorkspaceRef - providerMetadata - apiKey - basicAuth - oauth2ClientCredentials - oauth2PasswordCredentials description: >- Fields to update. Each entry must have a corresponding value in `connection`. Credential fields (`apiKey`, `basicAuth`, `oauth2ClientCredentials`, `oauth2PasswordCredentials`) must match the connection's existing auth scheme. example: - apiKey connection: title: Connection Request Body type: object properties: providerWorkspaceRef: type: string description: >- The ID of the provider workspace that this connection belongs to. providerMetadata: title: Provider Metadata type: object additionalProperties: title: Provider Metadata Info type: object required: - value - source properties: value: type: string description: The value of the metadata field example: '1234567890' source: type: string description: The source of the metadata field enum: - input - token - provider example: input displayName: type: string description: The human-readable name for the field example: Account ID groupName: type: string description: >- The name of the user group that has access to this installation. groupRef: type: string description: >- The ID of the user group that has access to this installation. example: group-123 consumerName: type: string description: >- The name of the consumer that has access to this installation. consumerRef: type: string description: The consumer reference. provider: type: string description: The provider name (e.g. "salesforce", "hubspot") apiKey: type: string description: The API key to use for the connection. customAuth: type: object description: >- Values used for custom auth input variables. Most values are strings (API keys, tokens, etc.), but structured values like arrays are also accepted — for example, googleWorkspaceDelegation sends a `scopes` array alongside the service account key. additionalProperties: true example: serviceAccountKey: base64encodedkey scopes: - https://www.googleapis.com/auth/calendar - https://mail.google.com/ basicAuth: type: object required: - username - password properties: username: type: string description: The username to use for the connection. password: type: string description: The password to use for the connection. oauth2ClientCredentials: type: object required: - clientId - clientSecret properties: clientId: type: string description: The client ID to use for the connection. clientSecret: type: string description: The client secret to use for the connection. scopes: type: array items: type: string description: The scopes for the tokens. oauth2PasswordCredentials: type: object required: - username - password - clientId - clientSecret properties: username: type: string description: The username to use for the connection. password: type: string description: The password to use for the connection. clientId: type: string description: The client ID to use for the connection. clientSecret: type: string description: The client secret to use for the connection. scopes: type: array items: type: string description: The scopes for the tokens. oauth2AuthorizationCode: title: OAuth2 Authorization Code type: object properties: accessToken: type: object required: - token description: The access token for the connection. properties: token: type: string expiresAt: type: string format: date-time issuedAt: type: string format: date-time refreshToken: type: object required: - token description: The refresh token to use for the connection. properties: token: type: string expiresAt: type: string format: date-time issuedAt: type: string format: date-time scopes: type: array items: type: string description: The scopes for the tokens. examples: rotateApiKey: summary: Rotate an API key value: updateMask: - apiKey connection: apiKey: new-api-key-value updateBasicAuth: summary: Update basic auth credentials value: updateMask: - basicAuth connection: basicAuth: username: new-username password: new-password updateWorkspaceRef: summary: Update provider workspace reference value: updateMask: - providerWorkspaceRef connection: providerWorkspaceRef: new-workspace-id responses: '200': description: Connection updated successfully. content: application/json: schema: title: Connection required: - id - createTime - group - consumer - projectId - provider - authScheme - status type: object properties: id: type: string description: The connection ID. example: connection-123 projectId: type: string description: The Ampersand project ID. example: project-456 provider: type: string description: The SaaS provider that this Connection is for. example: salesforce providerApp: title: Provider App required: - clientId - createTime - id - projectId - provider type: object properties: id: type: string description: The provider app ID. example: provider-app-123 projectId: type: string description: The Ampersand project ID. example: project-456 externalRef: type: string description: >- The ID used by the provider to identify the app (optional). example: external-id-123 provider: type: string description: The SaaS provider that this app connects to. example: salesforce clientId: type: string description: The OAuth client ID for this app. example: client-id-123 scopes: type: array description: The OAuth scopes for this app. items: type: string example: - oauth - offline - crm.read metadata: title: Provider App Metadata type: object description: >- Provider-specific configuration that extends the standard OAuth flow. properties: authQueryParams: type: object description: >- Additional query parameters to include in the OAuth authorization URL (e.g., optional_scope for HubSpot). additionalProperties: type: array items: type: string example: optional_scope: - automation.sequences.read providerParams: type: object description: >- Provider-specific string values keyed by names (e.g., packageInstallURL for Salesforce, gcpProjectId and gcpPubSubTopicName for Gmail). additionalProperties: type: string example: packageInstallURL: >- https://login.salesforce.com/packaging/installPackage.apexp?p0=04t123456789 gcpProjectId: my-gcp-project gcpPubSubTopicName: my-topic createTime: type: string description: The time the provider app was created. format: date-time updateTime: type: string description: The time the provider app was updated. format: date-time group: title: Group required: - createTime - groupName - groupRef - projectId type: object properties: groupRef: type: string description: >- The ID of the user group that has access to this installation. example: group-123 groupName: type: string description: >- The name of the user group that has access to this installation. example: Super Customer projectId: type: string description: The Ampersand project ID. example: project-456 createTime: type: string description: The time the group was created. format: date-time example: '2023-07-13T21:34:44.816Z' updateTime: type: string description: The time the group was last updated. format: date-time example: '2023-07-13T21:34:44.816Z' consumer: title: Consumer required: - consumerName - consumerRef - createTime - projectId type: object properties: consumerRef: type: string description: The consumer reference. example: consumer-123 consumerName: type: string description: The name of the consumer. example: Super Customer projectId: type: string description: The Ampersand project ID. example: project-456 createTime: type: string description: The time the consumer was created. format: date-time example: '2023-07-13T21:34:44.816Z' updateTime: type: string description: The time the consumer was last updated. format: date-time example: '2023-07-13T21:34:44.816Z' providerWorkspaceRef: type: string description: >- If available, the identifier for the provider workspace (e.g. the Salesforce subdomain) example: provider-workspace-123 providerConsumerRef: type: string description: >- If available, the ID that Salesforce/Hubspot uses to identify this user (e.g. Salesforce has IDs in the form of https://login.salesforce.com/id/00D4x0000019CQTEA2/0054x000000orJ4AA) example: provider-consumer-123 createTime: type: string description: The time the connection was created. format: date-time example: '2023-07-13T21:34:44.816Z' updateTime: type: string description: The time the connection was last updated. format: date-time example: '2023-07-13T21:34:44.816Z' authScheme: type: string description: The authentication scheme used for this connection. example: oauth2/authorizationCode enum: - none - apiKey - basic - oauth2/authorizationCode - oauth2/authorizationCodePKCE - oauth2/clientCredentials - oauth2/password status: type: string description: > The status of the connection. - `created`: The connection has just been created or the access token was just refreshed. - `working`: The connection has successfully been used to make a request. - `bad_credentials`: The connection encountered credential-related issues when making a request, or when attempting to refresh the access token. example: working enum: - created - working - bad_credentials oauth2AuthorizationCode: title: OAuth2 AuthorizationCode Token type: object properties: accessToken: type: object required: - token description: The access token for the connection. properties: token: type: string issuedAt: type: string format: date-time example: '2024-04-22T18:55:28.456076Z' expiresAt: type: string format: date-time example: '2024-10-22T18:55:28.456076Z' refreshToken: type: object required: - token description: The refresh token to use for the connection. properties: token: type: string issuedAt: type: string format: date-time example: '2024-04-22T18:55:28.456076Z' expiresAt: type: string format: date-time example: '2024-10-22T18:55:28.456076Z' scopes: type: array items: type: string description: The scopes for the tokens. apiKey: type: string description: The API key used while making the connection. example: api-key-123 providerMetadata: title: Provider Metadata type: object additionalProperties: title: Provider Metadata Info type: object required: - value - source properties: value: type: string description: The value of the metadata field example: '1234567890' source: type: string description: The source of the metadata field enum: - input - token - provider example: input displayName: type: string description: The human-readable name for the field example: Account ID example: id: c3a1f9d2-7b4e-4f8a-9e6d-2c5b8a3f1e7d projectId: a1b2c3d4-e5f6-4789-a012-3456789abcde provider: salesforce group: groupRef: 8f2e4a6b-1c3d-4e5f-9a7b-0d8e6f2c4a1b groupName: my-group consumer: consumerRef: d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a consumerName: my-consumer providerWorkspaceRef: my-org.my.salesforce.com authScheme: apiKey status: working createTime: '2023-07-13T21:34:44.816354Z' updateTime: '2024-01-15T10:22:33.000000Z' '400': description: >- Invalid update mask or request body. The response includes the list of allowed mask values. content: application/problem+json: schema: title: Input Validation Problem type: object allOf: - title: API Problem type: object allOf: - title: Problem description: > A Problem Details object (RFC 9457). Additional properties specific to the problem type may be present. type: object properties: type: type: string format: uri description: An absolute URI that identifies the problem type default: about:blank href: type: string format: uri description: >- An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML). title: type: string description: >- A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized). example: Service Unavailable status: type: integer format: int32 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 400 maximum: 600 exclusiveMaximum: true example: 503 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem instance: type: string format: uri description: >- An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: type: urn:problem-type:exampleOrganization:exampleProblem href: >- https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types title: Description of the type of problem that occurred status: 400 detail: Description of specific occurrence of the problem instance: urn:uuid:123e4567-e89b-12d3-a456-426614174000 properties: subsystem: type: string description: The subsystem that generated the problem example: api time: type: string format: date-time description: The time the problem occurred, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' requestId: type: string description: >- A unique identifier for the request, useful for debugging example: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715 causes: type: array items: type: string description: >- A brief description of something which caused the problem example: database connection failed example: - database connection failed - database query failed - unable to fetch user description: > A list of problems that caused this problem. This can be used to represent multiple root causes. There is no guaranteed ordering of the causes. remedy: type: string description: A brief description of how to resolve the problem example: Shorten your input to be under 100 characters supportEmail: type: string format: email description: An email address to contact for support example: support@withampersand.com supportPhone: type: string description: A phone number to contact for support example: +1-555-555-5555 supportUrl: type: string format: uri description: A URL to contact for support example: https://withampersand.com/support retryable: type: boolean description: Whether the request can be retried example: false retryAfter: type: string format: date-time description: >- A timestamp after which the request can be retried, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' context: type: object description: Additional context for the problem additionalProperties: true example: name: Rick Sanchez properties: issues: type: array items: title: Input Validation Issue type: object description: | An issue detected during input validation. allOf: - title: API Problem type: object allOf: - title: Problem description: > A Problem Details object (RFC 9457). Additional properties specific to the problem type may be present. type: object properties: type: type: string format: uri description: >- An absolute URI that identifies the problem type default: about:blank href: type: string format: uri description: >- An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML). title: type: string description: >- A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized). example: Service Unavailable status: type: integer format: int32 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 400 maximum: 600 exclusiveMaximum: true example: 503 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem instance: type: string format: uri description: >- An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: type: >- urn:problem-type:exampleOrganization:exampleProblem href: >- https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types title: >- Description of the type of problem that occurred status: 400 detail: >- Description of specific occurrence of the problem instance: urn:uuid:123e4567-e89b-12d3-a456-426614174000 properties: subsystem: type: string description: The subsystem that generated the problem example: api time: type: string format: date-time description: >- The time the problem occurred, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' requestId: type: string description: >- A unique identifier for the request, useful for debugging example: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715 causes: type: array items: type: string description: >- A brief description of something which caused the problem example: database connection failed example: - database connection failed - database query failed - unable to fetch user description: > A list of problems that caused this problem. This can be used to represent multiple root causes. There is no guaranteed ordering of the causes. remedy: type: string description: >- A brief description of how to resolve the problem example: Shorten your input to be under 100 characters supportEmail: type: string format: email description: An email address to contact for support example: support@withampersand.com supportPhone: type: string description: A phone number to contact for support example: +1-555-555-5555 supportUrl: type: string format: uri description: A URL to contact for support example: https://withampersand.com/support retryable: type: boolean description: Whether the request can be retried example: false retryAfter: type: string format: date-time description: >- A timestamp after which the request can be retried, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' context: type: object description: Additional context for the problem additionalProperties: true example: name: Rick Sanchez properties: in: type: string description: The location of the invalid input enum: - body - header - path - query name: type: string description: The name of the invalid input value: description: The value of the erroneous input example: type: about:blank title: Bad Request status: 400 detail: The input message is incorrect instance: 123456-1234-1235-4567489798 issues: - type: about:blank detail: exampleNumericProperty should be numeric in: path name: exampleNumericProperty value: abc - type: about:blank title: Input isn't valid with respect to schema detail: >- examplePropertyWithPattern a2345678901 doesn't match pattern '^\d{11}$' in: body name: items[0].examplePropertyWithPattern value: a2345678901 example: type: about:blank title: Bad Request status: 400 detail: Invalid update mask subsystem: api time: '2024-04-22T18:55:28.456076Z' requestId: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715 remedy: >- Allowed masks: 'providerWorkspaceRef, providerMetadata, apiKey, basicAuth, oauth2ClientCredentials, oauth2PasswordCredentials' retryable: false default: description: >- Error (e.g. connection not found, auth scheme mismatch, or server error). content: application/problem+json: schema: title: API Problem type: object allOf: - title: Problem description: > A Problem Details object (RFC 9457). Additional properties specific to the problem type may be present. type: object properties: type: type: string format: uri description: An absolute URI that identifies the problem type default: about:blank href: type: string format: uri description: >- An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML). title: type: string description: >- A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized). example: Service Unavailable status: type: integer format: int32 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 400 maximum: 600 exclusiveMaximum: true example: 503 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem instance: type: string format: uri description: >- An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: type: urn:problem-type:exampleOrganization:exampleProblem href: >- https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types title: Description of the type of problem that occurred status: 400 detail: Description of specific occurrence of the problem instance: urn:uuid:123e4567-e89b-12d3-a456-426614174000 properties: subsystem: type: string description: The subsystem that generated the problem example: api time: type: string format: date-time description: The time the problem occurred, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' requestId: type: string description: A unique identifier for the request, useful for debugging example: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715 causes: type: array items: type: string description: >- A brief description of something which caused the problem example: database connection failed example: - database connection failed - database query failed - unable to fetch user description: > A list of problems that caused this problem. This can be used to represent multiple root causes. There is no guaranteed ordering of the causes. remedy: type: string description: A brief description of how to resolve the problem example: Shorten your input to be under 100 characters supportEmail: type: string format: email description: An email address to contact for support example: support@withampersand.com supportPhone: type: string description: A phone number to contact for support example: +1-555-555-5555 supportUrl: type: string format: uri description: A URL to contact for support example: https://withampersand.com/support retryable: type: boolean description: Whether the request can be retried example: false retryAfter: type: string format: date-time description: >- A timestamp after which the request can be retried, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' context: type: object description: Additional context for the problem additionalProperties: true example: name: Rick Sanchez components: securitySchemes: APIKeyHeader: type: apiKey name: X-Api-Key in: header Bearer: type: http scheme: bearer bearerFormat: JWT ````