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

# Workspaces and apps

> A workspace is your organization. An app is one platform target inside it that owns its flows, placements, and experiments.

FlowPilot organizes everything under two levels. A **workspace** is your organization (it maps to a Clerk organization). An **app** is one platform target inside a workspace (iOS, Android, React Native, Flutter, or Web). Each app owns its own flows, placements, and experiments.

<Tip>
  New to FlowPilot? Read [Core concepts](/get-started/core-concepts) first to learn the terms used throughout these docs.
</Tip>

## Create or select a workspace

The first time you sign in you land on the workspace onboarding screen, titled "Welcome to FlowPilot" with the prompt "Create or select a workspace to get started".

<Steps>
  <Step title="Create a new workspace">
    In the **Create a new workspace** card, type a name in the **Workspace name** field (for example, `My Workspace`) and click **Create Workspace**. The button shows "Creating..." while it works, then takes you to the dashboard.
  </Step>

  <Step title="Or select an existing one">
    If you already belong to workspaces, a **Your workspaces** card lists them. Click one to switch to it and continue to the dashboard.
  </Step>
</Steps>

<Note>TODO: screenshot of the workspace onboarding screen.</Note>

## Create an app

Apps live under **Settings -> Apps**. Open the app switcher in the sidebar and choose **Manage apps**, or go to workspace settings and select the **Apps** tab.

<Steps>
  <Step title="Open the Apps tab">
    In **Settings**, select **Apps**. You see a card for each existing app and an **Add App** button.
  </Step>

  <Step title="Add the app">
    Click **Add App**. In the **Create App** dialog, fill in:

    * **App Name**: a display name, for example `My iOS App`.
    * **Platform**: one of **iOS**, **Android**, **React Native**, **Flutter**, or **Web**.
    * **Bundle ID (optional)**: your iOS bundle ID or Android package name, for example `com.example.myapp`. This is metadata only.

    Click **Create App** to finish.
  </Step>

  <Step title="Copy the App ID">
    Each app card shows an **App ID** with a copy button. This is the identifier you pass to a FlowPilot SDK as `appId`. Copy it now; you will need it when you configure the SDK.
  </Step>
</Steps>

<Note>TODO: screenshot of the Apps tab with an app card showing the App ID.</Note>

The platform options are exactly these (the value in parentheses is what the platform is stored as):

| Label        | Value          |
| ------------ | -------------- |
| iOS          | `ios`          |
| Android      | `android`      |
| React Native | `react_native` |
| Flutter      | `flutter`      |
| Web          | `web`          |

<Note>
  These docs cover the **iOS Swift SDK** and the **Expo / React Native SDK**. Create an app for the platform you target: iOS for the iOS SDK, and iOS and/or Android (set the platform to **React Native**) for the Expo SDK. The SDK integration pages live under the [iOS SDK](/ios-sdk/index) and [Expo SDK](/expo-sdk/index) tabs.
</Note>

### App ID vs bundle ID

* **App ID** is the value the SDK needs. Pass it to `FlowPilotConfiguration(appId:)`. See [Configuration](/ios-sdk/configuration).
* **Bundle ID** is optional metadata for your reference. The SDK does not use it to resolve flows.

The Apps tab also includes an **SDK Configuration** card that prints a ready-to-copy snippet using your App ID:

```swift theme={null}
FlowPilot.configure(
    FlowPilotConfiguration(
        apiKey: "fp_live_xxxxxxxxxxxxxxxx",
        appId: "your-app-id"
    )
)
```

## Switch between apps

The **app switcher** sits in the sidebar. It shows the current app's platform icon and name. Open it to:

* See an **Apps** list of every app in the workspace, each with its platform shown beneath the name. A check marks the active app.
* Choose **Manage apps** to jump to **Settings -> Apps**.

Selecting an app does three things:

1. Persists your choice (it is remembered the next time you open the dashboard).
2. Re-scopes the dashboard so flows, placements, experiments, and analytics all reflect the chosen app.
3. Clears stale data from the previous app so you never see mixed numbers.

On first load, FlowPilot selects the workspace's **default app** (or the first app if none is marked default).

## The default app

One app in the workspace is marked as the **default** and shows a "Default" badge on its card. The default app cannot be deleted. Other apps have a delete action, which removes the app along with all of its flows, placements, and experiments. This cannot be undone.

## Common mistakes

* **Designing flows under the wrong app.** Flows, placements, and experiments belong to a single app. Before you build, confirm the app switcher shows the app you intend to ship to.
* **App ID mismatch in the SDK.** The `appId` you pass to `FlowPilotConfiguration` must be the app that owns the placement you are presenting. If they differ, the placement resolves to no flow and nothing shows.
* **Confusing App ID with bundle ID.** The SDK uses the App ID. The bundle ID is metadata only.

## Related pages

* [API keys](/dashboard/api-keys)
* [Configuration](/ios-sdk/configuration)
* [Dashboard overview](/dashboard/index)