> ## Documentation Index > Fetch the complete documentation index at: https://docs.membrane.agency/llms.txt > Use this file to discover all available pages before exploring further. # update-connection > Write values to an existing connection: set `input` / `connectorParameters` (per the connector’s auth schema) or `credentials` (an API key/token, encrypted server-side, never echoed back). Use this to fill in auth the user volunteered — it pre-fills the connect form and can take the connection to READY. Each object replaces the prior one; merge client-side to retain keys. ## OpenAPI ````yaml /api-reference/membrane-api.json patch /connections/{id} openapi: 3.0.0 info: title: Membrane API description: API documentation for Membrane Engine version: '1.0' contact: {} servers: - url: https://api.getmembrane.com security: - bearer: [] tags: [] paths: /connections/{id}: patch: summary: update-connection description: >- Write values to an existing connection: set `input` / `connectorParameters` (per the connector’s auth schema) or `credentials` (an API key/token, encrypted server-side, never echoed back). Use this to fill in auth the user volunteered — it pre-fills the connect form and can take the connection to READY. Each object replaces the prior one; merge client-side to retain keys. operationId: updateConnection parameters: - name: id in: path required: true schema: type: string description: Connection id or connection key. requestBody: required: false content: application/json: schema: type: object properties: type: type: string enum: - connector - mcp - pipedream name: type: string meta: type: object additionalProperties: {} authOptionKey: type: string key: nullable: true type: string minLength: 1 maxLength: 100 integrationId: type: string integrationUuid: type: string integrationKey: type: string connectorId: type: string connectorUuid: type: string connectorKey: type: string connectorVersion: type: string externalAppId: type: string externalAppUuid: type: string credentials: {} connectorParameters: {} input: {} intent: description: >- [Experimental] Intent-based instruction for an agent to configure this element. type: string connector: description: >- Connector to build or edit inline. Creates and links a new connector when the connection has no connectorId; updates the linked connector when it does. Same shape as the connector write API. type: object properties: key: type: string name: type: string logoUri: type: string externalAppId: type: string externalAppUuid: type: string appUuid: description: '[INTERNAL] Deprecated: resolved to externalAppId' type: string categories: type: array items: type: string authOptions: description: >- [INTERNAL] Agent alias: an array of auth options, normalized server-side into the canonical single-auth top-level fields (one option) or the `options` record (multiple). Public callers use `options` directly; do not advertise this field. type: description: Authentication protocol used by the connector. type: string enum: - integration-app-token - membrane-token - oauth2 - oauth1 - client-credentials - proxy customCredentialsSchema: description: >- Additional JSON Schema for workspace-level overrides of credentials (e.g. BYO-OAuth clientId/clientSecret). allOf: - type: object inputSchema: description: >- JSON Schema for end-user input collected during connection (e.g. an API key or subdomain the user types in). allOf: - type: object parametersSchema: allOf: - type: object getCredentialsFromConnectionParameters: description: >- Function that derives auth credentials from connection parameters. Use for static-key auth (api-key, basic-auth) where the user-provided input IS the credential. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} refreshCredentials: description: >- Function that refreshes expired credentials. Implement for non-standard OAuth refresh flows or when additional credentials need to be refreshed alongside the OAuth token. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} makeApiClient: description: >- Function that configures the authenticated HTTP client used by connector API requests and actions. Typically a `mapping` type with `baseUri` and auth header wiring. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} getOAuthConfig: description: >- OAuth2: function returning `{ authorizeUri, tokenUri, scopes, noRefreshToken? }` — the authorize/token endpoint URLs and requested scopes. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} getTokenData: description: >- OAuth2: function invoked with the raw token response to extract token metadata. Rarely needed. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} getCredentialsFromAccessTokenResponse: description: >- OAuth2: function that transforms the token endpoint response into the final credentials object. Required for multi-tenant APIs (Microsoft) or APIs that require post-OAuth bootstrap calls. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} getCredentialsFromRefreshTokenResponse: description: >- OAuth2: function that transforms the refresh token endpoint response into the refreshed credentials. Required when refresh responses differ from initial-token responses. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} test: description: >- Function that verifies the connection by making a lightweight authenticated API call (typically a `rest-api-mapping` against a `/me`-style endpoint). type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} disconnect: description: >- Function that revokes credentials at the provider when the connection is removed. Implement only if the provider exposes a revoke endpoint. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} proxyKey: description: >- For `type: "proxy"` — identifies which proxy configuration the workspace should use. type: string ui: description: '[INTERNAL] Deprecated: Use inputSchema instead' type: object properties: schema: allOf: - type: object description: type: string helpUri: type: string additionalProperties: false options: description: >- Map of auth option key to auth configuration, for connectors that support multiple auth methods. Mutually exclusive with the top-level auth fields: use either the top-level fields (single-auth) OR `options` (multi-auth), not both. type: object additionalProperties: type: object properties: type: description: Authentication protocol used by the connector. type: string enum: - integration-app-token - membrane-token - oauth2 - oauth1 - client-credentials - proxy customCredentialsSchema: description: >- Additional JSON Schema for workspace-level overrides of credentials (e.g. BYO-OAuth clientId/clientSecret). allOf: - type: object inputSchema: description: >- JSON Schema for end-user input collected during connection (e.g. an API key or subdomain the user types in). allOf: - type: object parametersSchema: description: >- JSON Schema for connector-level parameters configured per integration (e.g. region, account ID). allOf: - type: object getCredentialsFromConnectionParameters: description: >- Function that derives auth credentials from connection parameters. Use for static-key auth (api-key, basic-auth) where the user-provided input IS the credential. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} refreshCredentials: description: >- Function that refreshes expired credentials. Implement for non-standard OAuth refresh flows or when additional credentials need to be refreshed alongside the OAuth token. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} makeApiClient: description: >- Function that configures the authenticated HTTP client used by connector API requests and actions. Typically a `mapping` type with `baseUri` and auth header wiring. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} getOAuthConfig: description: >- OAuth2: function returning `{ authorizeUri, tokenUri, scopes, noRefreshToken? }` — the authorize/token endpoint URLs and requested scopes. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} getTokenData: description: >- OAuth2: function invoked with the raw token response to extract token metadata. Rarely needed. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} getCredentialsFromAccessTokenResponse: description: >- OAuth2: function that transforms the token endpoint response into the final credentials object. Required for multi-tenant APIs (Microsoft) or APIs that require post-OAuth bootstrap calls. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} getCredentialsFromRefreshTokenResponse: description: >- OAuth2: function that transforms the refresh token endpoint response into the refreshed credentials. Required when refresh responses differ from initial-token responses. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} test: description: >- Function that verifies the connection by making a lightweight authenticated API call (typically a `rest-api-mapping` against a `/me`-style endpoint). type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} disconnect: description: >- Function that revokes credentials at the provider when the connection is removed. Implement only if the provider exposes a revoke endpoint. type: object properties: type: type: string enum: - mapping - rest-api-mapping - graphql-api-mapping - javascript description: description: >- Human-readable summary of what this function does, in plain language. Shown in the UI by default in place of the code. Populate it whenever you author or change the code. type: string additionalProperties: {} proxyKey: description: >- For `type: "proxy"` — identifies which proxy configuration the workspace should use. type: string ui: description: '[INTERNAL] Deprecated: Use inputSchema instead' type: object properties: schema: allOf: - type: object description: type: string helpUri: type: string additionalProperties: false title: type: string description: type: string enabled: {} additionalProperties: false additionalProperties: false externalApp: description: >- External app to create or edit inline. Creates and links a new app when the connection has no externalAppId; updates the linked app when it does. Same shape as the external-app write API. type: object properties: key: type: string minLength: 1 description: Machine key (e.g., "attio"). Unique per workspace. name: type: string minLength: 1 description: Human-readable app name (e.g., "Attio"). appUri: description: App's main URL (e.g., "https://attio.com"). type: string format: uri logoUri: type: string format: uri categories: description: >- [INTERNAL] Categorization tags used by the Universe catalog. type: array items: type: string defaultConnectorId: description: >- [INTERNAL] Connector ID surfaced as the default for this app in the Universe catalog. type: string basePackageId: description: '[INTERNAL] Base package ID this app is derived from.' type: string hasFreeTestAccount: description: '[INTERNAL] Whether the app has a free test account.' nullable: true type: boolean freeTestAccountGuide: description: '[INTERNAL] Guide for obtaining a free test account.' type: string freeTestAccountGuideVerifiedAt: description: >- [INTERNAL] When the free test account guide was last verified. nullable: true type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ tenantId: type: string additionalProperties: false additionalProperties: false responses: '200': description: >- Write values to an existing connection: set `input` / `connectorParameters` (per the connector’s auth schema) or `credentials` (an API key/token, encrypted server-side, never echoed back). Use this to fill in auth the user volunteered — it pre-fills the connect form and can take the connection to READY. Each object replaces the prior one; merge client-side to retain keys. content: application/json: schema: type: object properties: id: type: string description: >- Internal database ID of the element. Assigned by the API; unique per element. name: type: string userId: type: string tenantId: type: string ownerName: type: string nullable: true type: type: string enum: - connector - mcp - pipedream key: type: string isTest: type: boolean connected: type: boolean hasDocs: type: boolean docsCount: type: number docsSummary: type: string state: type: string enum: - BUILDING - CLIENT_ACTION_REQUIRED - CONFIGURATION_ERROR - SETUP_FAILED - READY - DISCONNECTING errors: type: array items: type: object requestError: allOf: - type: object integrationId: type: string connectorId: type: string externalAppId: type: string connectorVersion: type: string authOptionKey: type: string createdAt: type: string updatedAt: type: string lastActiveAt: type: string nextCredentialsRefreshAt: type: string nextRetryTimestamp: type: string retryAttempts: type: number canTest: type: boolean canRefreshCredentials: type: boolean archivedAt: type: string isDeactivated: type: boolean meta: type: object additionalProperties: {} buildingAgentSessionId: description: >- Session ID for building the element via intent-based endpoints (create/update with intent). Present when state is BUILDING. type: string clientAction: description: >- Action the client must perform to advance this connection. Present if and only if state is CLIENT_ACTION_REQUIRED. type: object properties: type: type: string enum: - connect - provide-input description: type: string uiUrl: type: string agentInstructions: type: string handoffAgentInstructions: type: string reason: description: >- [INTERNAL] Cause that triggered this client action; persisted so prompts can be re-rendered on read. type: string enum: - authenticate - reauthenticate - provide-input required: - type - description additionalProperties: false logoUri: description: >- Resolved app logo for this element (integration -> connector -> external app -> favicon). type: string input: {} required: - id - name - userId additionalProperties: false components: securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http ````