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

# Connect

> Add Connect to your app: create a session, launch it, handle the callback and confirm that the device is connected.

Connect is the flow where your customer signs in with their OEM account, grants consent and enrolls a device in your program. Flatpeak hosts it; your app opens it, and the customer returns to your app when they finish.

```mermaid actions={false} theme={"system"}
sequenceDiagram
    participant U as Customer
    participant A as Your app
    participant B as Your backend
    participant F as Flatpeak
    U->>A: Start Connect
    A->>B: Request Connect session
    B->>F: Create Connect session (oem_id, program_id)
    F-->>B: Session ID, target_url
    B-->>A: Session ID, target_url
    A->>F: Launch Connect
    U->>F: Sign in with OEM account, grant consent
    F-->>A: Redirect to callback_url (connect_session)
    B->>F: Retrieve Connect session
    B->>F: Retrieve device
```

## Integrate

### 1. Create a session

Call [create a Connect session](/docs/fleet-api/reference/connect-sessions/create.md) from your backend. A session launches Connect once without exposing your secret key, so create one for each launch, even for the same customer. It expires at `time_expiry`.

| Field | Value |
| :- | :- |
| `oem_id` | The OEM the customer signs in with, from [list all OEMs](/docs/fleet-api/reference/oems/list.md). Fixed for the session. `oem_6a3a8dada72cd0a249ff9528` is a simulator |
| `program_id` | The [program](/docs/fleet-api/guides/programs.md) the device enrolls in. The customer confirms it; they do not choose from a list |
| `callback_url` | Where the customer returns. Use a deep link into your app, such as `myapp://flatpeak/complete` |
| `signup_reference` | Optional. The reference your program's `enrollment.signup_url` received, when the customer chose a managed tariff in an OEM app. See [Sign-up from an OEM app](/docs/fleet-api/guides/programs.md#sign-up-from-an-oem-app) |

### 2. Launch Connect

Append the session `id` to `target_url` as the `connect_session` query parameter and open the URL:

```http theme={"system"}
https://universal.flatpeak.com/?connect_session=cos_6a3196d6e61a44f33f7307ed
```

The OEM app opens if it is installed; otherwise the link opens in a browser.

### 3. The customer completes Connect

1. Signs in with their OEM account. The OEM hosts this step and you cannot customize it.
2. Grants consent: the `TELEMETRY`, `CONTROL`, `LOCATION` and `SETTINGS` scopes.
3. Confirms the program, and connects a tariff if the location has none.
4. Returns to your `callback_url`. Canceling sign-in or declining consent also returns there.

The OEM app keeps working and shows that third-party control is active.

![Flatpeak Connect flow](https://mintcdn.com/flatpeak-d495c19e/2B6nWUU4-c2pSD3E/images/fleet/connect/connect-flow.png?fit=max\&auto=format\&n=2B6nWUU4-c2pSD3E\&q=85\&s=80d49f30ff49758cefffba42c7403534)

Left and right: your app. Middle: the OEM app or web portal.

### 4. Handle the callback

The customer returns with the session ID in the `connect_session` query parameter. [Retrieve the Connect session](/docs/fleet-api/reference/connect-sessions/retrieve.md) and read `device_id`, which is `null` if the customer left without connecting a device. Store the ID against your customer record.

### 5. Confirm the connection

[Retrieve the device](/docs/fleet-api/reference/devices/retrieve.md) and check `consent_scopes`. Flatpeak creates the enrollment when the customer confirms. Read its `enrollment_state` from the [Enrollments API](/docs/fleet-api/reference/vpp-enrollments/list.md): `PENDING` until onboarding completes, then `ACTIVE`.

For a server-side signal, handle the `device.connect` [event](/docs/fleet-api/guides/platform/events.md).

Test with the simulator OEM, then with a real device and OEM account before you go live.

## Disconnect and reconnect

| The customer wants to | Do this |
| :- | :- |
| Leave the program | Call [unenroll](/docs/fleet-api/reference/vpp-enrollments/unenroll.md) |
| Reconnect | Create a session with the device's `oem_id`, the `program_id` and your `callback_url`, and launch Connect |

A customer can also ask to leave from the OEM app. That request waits for your approval: see [requests to leave](/docs/fleet-api/guides/programs/enrollment-states.md#requests-to-leave).

The customer can withdraw consent, and dispatch stops at once. The Fleet API has no call for it, so your app cannot do it for them. `device.update` fires, the enrollment is suspended with `CONSENT_REVOKED`, and the withdrawal is recorded in [consent history](/docs/fleet-api/reference/devices/consent-history.md). Consent does not expire. To restore it, the customer completes Connect again.

## Company details

> [!WARNING]
>
> The law requires these details, and wrong or missing details can lead to account suspension.

GDPR and other data protection laws require you to tell the customer who accesses their device data and how it is used, for each consent scope. Enter these in [Console](https://console.flatpeak.com) > **Compliance**:

| Field | Description | Example |
| :- | :- | :- |
| Company trading name | Shown to the customer on the consent screen | *Phase Energy* |
| Company legal name | Your registered legal entity | *Phase Energy Inc* |
| Terms of Service URL | Must name Flatpeak as a sub-processor and link to your help page | `https://phase.com/terms` |
| Support email | Your support address | `help@phase.com` |

![Consent screen showing the company trading name, legal name and a link to the terms of service](https://mintcdn.com/flatpeak-d495c19e/2B6nWUU4-c2pSD3E/images/fleet/connect/consent-oem.png?fit=max\&auto=format\&n=2B6nWUU4-c2pSD3E\&q=85\&s=9f06b5026cca9813a34687a095cfa18b)

The consent screen shows your trading name, legal name and terms link


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