Get user information in mobile and Portal widgets

Fluid adds a public_id query parameter before it opens either of these widgets:

A custom widget in the Fluid mobile app
A Droplet iframe widget in Portal

For example, Fluid can open your widget at this URL:

https://widgets.example.com/earnings?public_id=0190a1b2-c3d4-7000-8000-000000000001

Use public_id to resolve the current user’s information from your server. Do not use it to authenticate the user or the API request.

Treat public_id as an opaque identifier. It is not a username, slug, user UUID, customer UUID, legacy numeric membership ID, or Bearer token.

What `public_id` identifies

public_id is a stable, company-scoped identity identifier. For an ordinary member-backed account, it is the member’s stable UUID. An admin-only account can receive an admin identity UUID instead. Do not parse the value or infer a record type from it. Send it to the resolver and use the returned user data.

Resolve the user from your server

Keep your Droplet installation token on your server. Never expose it in iframe JavaScript, mobile widget content, a query parameter, or a response to the browser.

Read public_id from the widget URL

Read the value as an opaque string. Handle a missing value before you request user information.

const query = new URLSearchParams(window.location.search);
const publicId = query.get("public_id");

if (!publicId) {
  throw new Error("Fluid did not provide public_id");
}

Send public_id to your server

Send the value to an authenticated route in your widget application. Your server must select the Droplet installation for the current company. Do not accept a company identifier from the browser as proof of that selection.

const response = await fetch("/api/widget-user", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ public_id: publicId }),
});

Call the Fluid resolver

From your server, call GET /api/v2025-06/users/by-public-id/{public_id}. Authenticate with the installation token for the company that owns the widget.

const fluidResponse = await fetch(
  `https://api.fluid.app/api/v2025-06/users/by-public-id/${encodeURIComponent(publicId)}`,
  {
    headers: {
      Authorization: `Bearer ${installation.authenticationToken}`,
    },
  },
);

The resolver searches only the company associated with the Bearer token. It does not create a Fluid session or turn public_id into a login credential.

Request the required scope

Request the users scope for your Droplet before a company installs it. The resolver returns 403 when the installation does not have this scope. Use the installation’s authentication_token as the Bearer token. See Build and publish a Fluid Droplet for the installation credential flow.

Handle resolver errors

Handle each response separately:

Status	Meaning	Action
`401`	The Bearer token is missing or invalid.	Check the stored installation credential. Do not retry with `public_id` as a credential.
`403`	The installation does not have the `users` scope.	Update the Droplet’s requested scopes and reinstall it.
`404`	No matching membership exists in the authenticated company.	Show an unavailable state. Do not search another company.

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

Get user information in mobile and Portal widgets

What `public_id` identifies

Resolve the user from your server

Request the required scope

Handle resolver errors

​What public_id identifies

​Resolve the user from your server

​Request the required scope

​Handle resolver errors

What `public_id` identifies

Resolve the user from your server

Request the required scope

Handle resolver errors