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

# Integrations

Integration represents a relationship between your product and a given external app.

## Integration Definition

Integration looks like this:

```yaml theme={null}
name: Github
key: github
logoUri: https://static.integration.app/connectors/github/logo.png
appUuid: c04f4af3-1704-4693-86a4-9af453205335
connectorId: 62471fad996d5c297ae43f5f
connectorVersion: 2.3.1
authOptions:
  - title: API Key
    description: Connect using one of the Github API key types
    type: client-credentials
  - title: OAuth
    description: Connect in one click by approving this app's access
    type: oauth2
```

In this definition:

* `logoUri` - URL of the publicly available image with the integration logo.
* `appUuid` - uuid of the [External App](/reference/workspace-elements/external-apps) this integration is related to.
* `connectorId` - id of the [Connector](/reference/workspace-elements/connectors) this integration uses.
* `connectorVersion` - a published version of the connector. If empty, development (unpublished) version of the connector is used.
* `authOptions` (read-only) - list of available authentication options based on the connector and integration parameters. The format of auth options matches the auth config from the [Connector](/reference/workspace-elements/connectors) definition with all the [Formulas](/docs/references/formulas) resolved (if there were any).

## Connector Parameters

If the connector used by an integration has [parameters](/reference/workspace-elements/connectors#connector-parameters) (for example `clientId` and `clientSecret` for OAuth), you can store their values on the integration level.

For security reasons, parameters are not saved as a part of the integration definition and are not returned in the response by default.

Read them by fetching the integration with `?includeSecrets=true` (the response includes both `parameters` and `optionsConfig`), and write them with [Patch integration](/api-reference/integrations/update-integration-partially). Where you put them depends on the connector's auth options:

* **Single auth option** — store the values at the top level, under `parameters`:

  ```json theme={null}
  { "parameters": { "clientId": "...", "clientSecret": "..." } }
  ```

* **[Multiple auth options](/reference/workspace-elements/connectors#connector-options)** — store each option's values under `optionsConfig.<optionKey>.parameters`:

  ```json theme={null}
  { "optionsConfig": { "oauth": { "parameters": { "clientId": "...", "clientSecret": "..." } } } }
  ```

<Warning>
  `PATCH` replaces `parameters` and `optionsConfig` as **whole objects** — there's no deep merge. Send the full value
  you want to keep; any option you omit from `optionsConfig` is cleared.
</Warning>

The [Get](/api-reference/integrations/get-integration-parameters) and [Set integration parameters](/api-reference/integrations/set-integration-parameters) endpoints are a convenience for the top-level `parameters` only and don't cover per-option values. If you're updating parameters programmatically, prefer the `?includeSecrets=true` + [Patch integration](/api-reference/integrations/update-integration-partially) approach above — it covers both.

In the UI, you can edit these values in the integration config. For a connector with a single auth option, they appear in the **Parameters** section:

<Frame>
  <img src="https://mintcdn.com/membrane/geUwZB3OLWiy68_0/images/integration-top-level-parameters.png?fit=max&auto=format&n=geUwZB3OLWiy68_0&q=85&s=72a8ccca8dd5dee66f653045940cfa0f" alt="Top-level connector parameters" width="1564" height="598" data-path="images/integration-top-level-parameters.png" />
</Frame>

For a connector with multiple auth options, each option has its own parameters under **Options**:

<Frame>
  <img src="https://mintcdn.com/membrane/geUwZB3OLWiy68_0/images/integration-auth-option-parameters.png?fit=max&auto=format&n=geUwZB3OLWiy68_0&q=85&s=9d2f0ccefcbb393c8abb4c10d25e7470" alt="Per-auth-option connector parameters" width="1578" height="860" data-path="images/integration-auth-option-parameters.png" />
</Frame>