> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluid.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract. > Authenticate with the header Authorization: Bearer ; public storefront read endpoints require no auth. > To sign a new merchant up for Fluid programmatically, call POST https://api.fluid.app/api/company with no credentials, as described in /api/agent-signup. Do not automate the signup form or book a demo. The merchant must open the emailed sign-in link and create an API token before authenticated calls are possible. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > When the same operation exists on more than one surface, use the newest: dated API versions are newer than unversioned ones, and later dates win (v2026-04 > v2025-06 > unversioned v0/v1.1). Fall back to a legacy or unversioned operation only when no newer versioned equivalent exists — the company-v0 notes below list the known superseded operations. /api/company/v1 and /api/v1/... paths are documented in no spec here and must never be used (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only where a spec documents it — in practice the unversioned company-v0 admin surface; every versioned surface uses cursor pagination. > Navigation menu management is documented in themes/navigation-menus. These unversioned admin endpoints (/api/menus and nested menu_items) are verified against the implementation but are not yet in the synced OpenAPI specs. Use that reference for menu payloads and its flat page/per_page pagination; missing spec coverage does not make these endpoints unavailable. > The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas); api-reference/company-v0.yaml covers the legacy unversioned company admin surface (/api/... paths, bearer-authenticated — company settings and management, customers, users, roles, subscription plans, subscription bundles, subscriptions, media, pages, catch-ups, inventory levels, domains, agreements, and admin order actions). company-v0 caveats: it is the legacy v0 admin contract and its lists use flat page/per_page offset pagination, which is expected there despite the general cursor-pagination rule; where an operation exists in both company-v0 and a versioned spec, prefer the versioned spec — the subscriptions lifecycle (list/create/show/update, cancel, pause, reactivate, resume, retry, skip, failed-cycle-waiver, discounts) and subscription bundles are superseded by checkout-v2026-04, and company pages/media CRUD plus the public pages, categories, products, and media list endpoints are superseded by storefront-v2026-04. Subscription plan management (/api/subscription_plans, resource-wrapped {"subscription_plan": {...}} bodies) exists only in company-v0. api-reference/members-v2025-06.yaml covers the v2025-06 unified Member identity surface (/api/v2025-06/members/... paths, bearer-authenticated — member list/create/show/update, lookup by email/username/external_id/legacy_customer_id, member-type assignment, and the sponsor genealogy read). Prefer it over the customers and reps surfaces when the member type matters: /customers does not serialize member_type. api-reference/analytics-v2026-04.yaml covers the v2026-04 Home dashboard analytics surface (/api/v202604/analytics/dashboard/... paths, bearer-authenticated — read-only endpoints for the Home > Overview, Home > Live, and Home > Field tabs, each accepting an optional country ISO alpha-2 query param that scopes aggregations to a single country). > api-reference/analytics-v0.yaml covers the unversioned analytics surface that backs the fluid-admin Traffic tab (/api/analytics/... and /api/analytics/traffic/... paths, bearer-authenticated — the legacy shares/views/visitors summary plus traffic overview, ranked campaigns, sources, geographies, flows, and per-rep breakdown, all sharing one reporting-period contract). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. > Portal Definition authoring edits and synchronizes the portal JSON resource graph. Widget Package authoring builds either a company-owned or Droplet-owned Remote DOM package. These are separate contracts; do not imply that one defines the other. > For Widget Package worker code, use only @fluid-app/portal-sdk/widgets/worker. Use only the Portal Definition and Widget Package workflows and public entry points documented here; do not infer support for undocumented surfaces. > Every portal function and declarative capability used by a widget must appear in that widget's uses array. Use the same typed function value in uses; do not invent capability-name strings. > Widget styling must use the portal's semantic theme variables for colors, typography, spacing, radii, borders, focus, and charts whenever a token represents the visual decision. Do not create a separate light or dark palette or duplicate theme controls as widget properties. > Prefer worker-safe Fluid UI components exported by @fluid-app/portal-sdk/widgets/worker when they fit the interaction. When no exported component fits, use semantic HTML, accessible behavior, and the portal theme variables. > A Portal Definition push updates the remote working definition. A portal version is an immutable snapshot, and activation is a separate live release operation. # Roles > Create roles, choose what each role can see and change, add users to them, and preview the admin as a role. Use the **Roles** screen to control what people can see and do in the admin. A role is a set of permissions, and every user you add to a role gets those permissions. ## Where to find it In the admin, click the **Settings** gear in the top bar. In the Settings sidebar, under **Company**, select **Roles**. What you can do here depends on your own role's **Roles** permissions, in the **Settings** category. To add users to a role, your role also needs to view **Company Admins**, in the **People** category. If an action is missing or fails, ask an admin who manages roles to update your role. ## The roles list The list shows your company's roles, including any that Fluid created for your company. Click **Create Role** to add one. * The **All** and **Unused** tabs filter the list. **Unused** shows roles that have no users. * Some roles are used by integrations, not people, so they have no users and appear under **Unused**. These include the default **Droplet**, **Partner Token**, and **Company API Token** roles. Installing a droplet can also add a role named **Droplet:** followed by the droplet's name. Before you delete one of these roles, see [Delete a role](#delete-a-role). * Use the search box to find a role by name. The list has these columns: * **Title**: the role's name. * **Users**: how many users have the role. * **Date Created**: the date the role was created. Click a row to open the role. Each row's three-dot menu has **Preview**, **Edit**, **Add User**, **Duplicate**, and **Delete**. To duplicate or delete several roles at once, select their rows and use the three-dot menu in the table header, for example, **Delete 3 rows**. ## The role page The role page opens when you click **Create Role** or open a role from the list. It's titled **New Role** for a new role and **Edit Role** for a saved one. * **Role Name**: the role's name, for example, Sales Manager. You set it when you create the role. On a saved role you can still type in this field, but saving doesn't change the name. * **Permissions**, **Members**, and **Droplets** tabs. On a new role, **Members** and **Droplets** show **(save first)** and open only after you save. * **Save**, in the page header. * **Actions**, in the page header of a saved role: a menu with **Add User**, **Preview as this Role**, and **Delete**. * **Back** returns you to the roles list. ### Permissions tab The **Permissions** tab groups permissions into category cards: **Commerce**, **People**, **Content & Website**, **Tools & Messaging**, and **Settings**. If some permissions don't belong to these categories, an **Other** card holds them. * Type in **Search permissions...** to find a category by name, or an area by its name or description. The list narrows to what matches, and the matching categories open. * Each card has an access button. It shows **Full access** when every permission in the category is on, **No access** when none are, and **Custom** otherwise. * The access button's menu sets every area in the category to **Full access** (every permission on), **View only** (view permissions on, everything else off), or **No access**. While the card is closed, **Customize** opens it. * Click a card to open it. Each area in it, such as **Orders** or **Products**, has its own access menu with **No access**, **View only**, and **Full access**. **View only** appears only for areas that have a view permission. * Click an area to see its individual permissions. Each one has a short description, a switch, and an info icon that explains what it covers. When a permission belongs to a screen, its info icon also shows **View in app**, which opens that screen. **View in app** leaves the role page without saving, so click **Save** first. ### Members tab The **Members** tab lists the users who have this role, with their **Name**, **Email**, and **Status** (**Active** or **Inactive**). Use the search box to find a member. Click a row, or choose **Edit User** from its three-dot menu, to open that user's page. You can also remove the user from the role here; see [Remove a user from a role](#remove-a-user-from-a-role). ### Droplets tab The **Droplets** tab lists the droplets installed for your company, with each droplet's **Name**, **Scopes**, and **Status** (**Active** or **Inactive**). You can't change anything on this tab. Click a row, or choose **View Droplet** from its three-dot menu, to open the droplet. ## Create a role On the **Roles** screen, click **Create Role**. The **New Role** page opens. Enter a **Role Name**. Each role in your company needs its own name. Choose it carefully, because you can't change it after you save. On the **Permissions** tab, set each category's access. To give access to only part of a category, open the card and set each area, or turn individual permissions on and off. Click **Save** in the page header. Fluid creates the role and reopens its page as a saved role, where the **Members** and **Droplets** tabs are available. ## Edit a role In the roles list, click the role, or choose **Edit** from its three-dot menu. On the **Permissions** tab, change the role's access. Click **Save** in the page header. You stay on the role's page. ## Add users to a role In the roles list, choose **Add User** from the role's three-dot menu. Or open the role and choose **Actions** > **Add User**. The **Members** tab opens with a dialog titled **Add Members to** and the role's name. Search by name or email, then click each user you want to add. The list shows only users who don't already have this role. Click **Add**. The button shows how many users you selected, for example **Add (2)**. The users appear on the **Members** tab. ## Remove a user from a role Open the role's **Members** tab and choose **Remove from Role** from the user's three-dot menu. The removal takes effect right away, with no confirmation step. ## Preview a role Preview shows you the admin with a role's permissions, so you can check what its users can reach. In the roles list, choose **Preview** from the role's three-dot menu. Or open the role and choose **Actions** > **Preview as this Role**. The admin opens the first main screen the role can view, such as **Getting Started** or **Orders**. If the role can't view any of the main screens, you land on a blocked page instead. A banner at the top shows **Previewing as** and the role's name. Move around the admin to check what the role can reach. Click **Exit Preview** in the banner to return to your normal view. Reloading the page also ends the preview. During a preview, the menus and screens reflect what the role can use: * Some menu entries and buttons the role can't use are hidden. * Others stay on screen as a dashed label with a crossed-out eye that names the missing permission, for example **Orders · View**. * A page the role can't open shows **Role Preview: Missing Permission** and names the permission the role lacks. * When the role is blocked from a page, the banner shows a count of access denials. Click the count to see the list. Preview changes what you see, not what you can do. Anything you change during a preview still uses your own access. ## Duplicate a role In the roles list, choose **Duplicate** from the role's three-dot menu. In the **Duplicate Role** dialog, click **Duplicate**. The copy is named after the original with `(Copy)` added, or `(Copy 1)`, `(Copy 2)`, and so on if that name is taken. It has the same permissions, but Fluid doesn't copy the role's users. ## Delete a role Users assigned to a deleted role lose that role's permissions. Don't delete the **Partner Token** or **Company API Token** roles. Your partner tokens and your company API token use them, and once the role is gone, they lose the access it gave them. Leave the droplet roles in place too. In the roles list, choose **Delete** from the role's three-dot menu. Or open the role and choose **Actions** > **Delete**. In the **Delete Role** dialog, click **Delete**. You can't undo this. ## FAQ **Save** turns on only after you change the role, for example by turning a permission on or off. Until then, there's nothing to save. No. You set a role's name when you create it. On a saved role you can still type in **Role Name**, and **Save** turns on, but saving doesn't change the name. The button shows **Full access** only when every permission in the category is on. **View only** leaves the category's other permissions off, so the button shows **Custom**. Open the card to see each area's access. While you're searching, a card's access button and its menu cover only the areas the search shows. Clear the search to set a whole category at once. Either every user already has this role, or your own role can't view **Company Admins**, in the **People** category. In the second case, ask an admin who manages roles to update your role. No. Preview uses the role's saved permissions. Click **Save** before you preview a role you just changed. Yes. Removing a user from one role doesn't change their other roles. Open the role's **Permissions** tab and type the area's name, such as **Company Settings**, in **Search permissions...**. The matching category opens with that area in it. ## Related pages * [Settings](/help/admin/settings) * [Droplets](/concepts/droplets) * [API authentication](/api/authentication)