Sign-in and users

Let your app's users sign in, find out who they are, and control what they can reach.

The Shell signs your users in, so your app never handles passwords or sign-in screens. Your app asks the Shell for the signed-in user's token and uses it to call Groundfloor.

These are your app's users, not your team: they sign in to your Shell site, not the Client Portal.

In the Client Portal, go to Administer → App authentication and choose a mode. The Shell picks it up automatically:

Mode	Users sign in with	Users are managed in
None	Nothing: the app is open, or handles access itself	—
Groundfloor	A sign-in page Groundfloor hosts for your workspace	The Users tab of App authentication
External	Your own identity provider, such as Okta, Microsoft Entra ID or Auth0	Your identity provider

See App authentication for setting each one up.

Get the user's token

The Shell makes a function available to your app:

const token = await window.__GF_GET_ACCESS_TOKEN__?.(); // null when nobody is signed in

Send it as Authorization: Bearer <token> to Groundfloor's API. The starter kit's helpers, for data and feature flags, already do this. The function returns a fresh token each time, so call it before each request rather than storing the result.

Know who the user is

The token is a JWT. These claims identify the user and where the token came from:

Claim	What it is
`sub`	The user's ID. Store this to tie records to the user; with Groundfloor sign-in it doesn't change
`external_user_id`	Same value as `sub` on Groundfloor sign-in
`external_tenant_id`	Your workspace's ID — the same for every user
`organization`	The customer company the user belongs to, when Multi-tenant is on in App authentication
`realm_access.roles`	The user's roles, with Groundfloor sign-in. See What users can reach
`iss`	The issuer: who signed the token. With Groundfloor sign-in it's unique to your workspace
`azp`	The client the token was issued to: `shell` with Groundfloor sign-in, or your client ID with External sign-in

With External sign-in, sub comes from your own identity provider.

A backend must check the signature, iss, exp and which client the token was issued to before trusting any of these. See Who can reach your Service.

If your app serves several customer companies, turn on Multi-tenant and keep each company's data apart by the organization claim. Don't use external_tenant_id for that: it identifies your workspace, not the user's company.

Pages anyone can open

By default every page of your app needs a signed-in user. To make a page public, set "visibility": "public" on its route in the manifest.

What users can reach

Signed-in users get a role in your workspace's site, such as viewer, user or admin, set on the Users tab of App authentication. Roles decide which apps they can open and which data they can read or change:

Apps: each app is open to everyone, or restricted to chosen roles. See What is an app.
Data: each collection grants read, write and delete per role. New collections are open only to admins until you grant access. See Data.

Manage both on the Site access page.

A user's roles are in their token's realm_access.roles claim, as a list such as ["user", "offline_access", "default-roles-…"]. Look for the roles you use and ignore the rest. Your own backend reads them there to decide what the user may do. With External sign-in, roles come from your identity provider, in whatever claim it uses.

Next steps

Data — read and write records as the signed-in user.
App authentication — set up a sign-in mode.