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

# Fully embedded

You show the list of connectors and collect the credentials inside your own product. You send the credentials to Chift when you create the connection. Your end-user never sees a Chift page.

<Note>
  Fully embedded is the most work for a small gain over the [embedded connector-picker](/developer-guides/unified-api/how-to-connect/embedded-connector-picker), which is the recommended mode. You build and maintain the credential forms of every connector. Choose it only if you must hide every Chift page.
</Note>

## Which connectors support Fully embedded

| Connector authentication | Fully embedded |
| - | - |
| Credentials only (API key, login and password, token) | Supported |
| OAuth2 | Supported with [pre-OAuth2](#oauth2-connectors-pre-oauth2) only |
| Local agent | Not supported. Use the [embedded connector-picker](/developer-guides/unified-api/how-to-connect/embedded-connector-picker) |

<Warning>
  Fully embedded does not support **mandatory post-connections**. A post-connection value, such as the accounting folder, can only be read once the connection works, so you cannot send it when you create the connection. Configure the connector without mandatory post-connections when you [activate the connector](/platform/getting-started/activate-connector).
</Warning>

## Steps

<Steps>
  <Step title="Create the consumer">
    Create one consumer per end-user. Store the returned `consumerid` on your end-user record. You reuse it for every connection that end-user makes.

    ```bash theme={null}
    curl -X POST https://api.chift.eu/consumers \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Your end-user's company name",
        "internal_reference": "your-internal-end-user-id",
        "email": "contact@your-end-user.example",
        "redirect_url": "https://yourapp.example/integrations/callback"
      }'
    ```

    | Field | Required | Notes |
    | - | - | - |
    | `name` | Yes | Shown in your Chift platform and used in automated emails. |
    | `email` | No | Used for [activation reminders](/platform/user-onboarding/email-reminders) and emailing the [local agent](/platform/advanced/local-agent) installer. |
    | `internal_reference` | No | Your own ID for this end-user. Makes reconciliation much easier later. |
    | `redirect_url` | No | Where the end-user lands after activation. Can also be set once for the whole account. See [Activation links and redirects](/developer-guides/unified-api/activation-and-redirects). |

    <Note>
      Already have a `consumerid` for this end-user? Skip this step.
    </Note>

    [API reference: Create new consumer ↗](/api-reference/endpoints/consumers/create-new-consumer)
  </Step>

  <Step title="Fetch the connectors and their credentials">
    ```bash theme={null}
    curl "https://api.chift.eu/integrations?status=active" \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    Besides the fields used to show the connectors (see [Embedded connector-picker](/developer-guides/unified-api/how-to-connect/embedded-connector-picker)), each entry has:

    * `credentials`: the credentials to send when you create the connection. Each one has a `name`, an `optional` flag and a `visibility`:
      * `consumer`: your end-user provides it.
      * `connector`: you set it when you activate the connector. Do not send it.
      * `both`: send it, unless you set it when you activated the connector.
    * `local_agent`: `true` for a local agent connector, which Fully embedded does not support.

    [API reference: Get list of integrations ↗](/api-reference/endpoints/integrations/get-list-of-integrations)
  </Step>

  <Step title="Collect the credentials">
    Show the connectors in your own UI. For the connector your end-user picks, show a form with its credentials.

    <Warning>
      Do not hardcode the credentials of a connector. They can change with new connector releases. Build the form from `GET /integrations` each time.
    </Warning>
  </Step>

  <Step title="Create the connection">
    Send `integrationid`, `name` and `credentials`. Each credential is a `key` (the credential `name`) and a `value`:

    ```bash theme={null}
    curl -X POST https://api.chift.eu/consumers/{consumerid}/connections \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "integrationid": 42,
        "name": "My accounting connection",
        "credentials": [
          { "key": "api_key", "value": "the-end-user-api-key" }
        ]
      }'
    ```

    | Field | Required | Notes |
    | - | - | - |
    | `integrationid` | Yes | Integer from the first step. |
    | `name` | Yes | Display name of the connection. Required with `credentials`. |
    | `credentials` | Yes | The credentials of the connector, as `key` and `value` pairs. |

    When the connector supports it, Chift tests the credentials before it activates the connection. The call returns a `url`. Ignore it when the connection is active.

    | Error | HTTP | Cause |
    | - | - | - |
    | `ERROR_CONNECTION_CREDENTIALS_NOT_SUPPORTED` | 400 | A required credential is missing. |
    | `ERROR_CONNECTION_CREDENTIALS_NOT_CORRECT` | 401 | The credentials are not correct. The connection is not created. |

    [API reference: Add new connection ↗](/api-reference/endpoints/connections/add-new-connection)
  </Step>

  <Step title="Check the connection">
    Reload the consumer's connections. Find the connection by its `integrationid`: a consumer has only one connection per connector. Confirm its `status` is `active`. Then you can call the Unified API for that consumer.

    ```bash theme={null}
    curl https://api.chift.eu/consumers/{consumerid}/connections \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    [API reference: Get connections ↗](/api-reference/endpoints/connections/get-connections)
  </Step>
</Steps>

## Update the credentials

Use [Update an existing connection](/api-reference/endpoints/connections/update-an-existing-connection) with the new `credentials`. Chift tests them again. An update replaces all the credentials of the connection, so send every credential again.

## OAuth2 connectors: pre-OAuth2

With pre-OAuth2, you run the OAuth2 flow of the connector's software yourself. Then you create the connection with the tokens in `credentials`:

| Key | Required | Notes |
| - | - | - |
| `access_token` | Yes | The access token. |
| `last_refresh_date` | Yes | When the access token was issued, for example `2026-10-05T14:48:00.000Z`. |
| `refresh_token` | Depends on the connector | The refresh token. |
| `expires_at` | Depends on the connector | When the access token expires. |

Add the other credentials of the connector, if it has any.

<Note>
  Chift sets up pre-OAuth2 with you. [Contact us](https://www.chift.eu/contact) to enable it for your account and connectors.
</Note>

Without pre-OAuth2, an OAuth2 connector needs the Chift connector page: use the [embedded connector-picker](/developer-guides/unified-api/how-to-connect/embedded-connector-picker).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.