AUTH GUIDE / Architecture
The deeper picture
One person.
Several places to belong.
Ana can own a company in Maya’s product, join another company, and later build a product herself. Her identity stays the same. Each place has its own access rules.
The people and products below are fictional examples.
01 / The nesting
Your workspace contains your customer companies.
Maya runs Field Notes. Her operator organization owns the product, its brand and its domains. Ana’s company is one customer account inside it.
CUSTOMER ACCOUNT A
Acme Imports
CUSTOMER ACCOUNT B
Beta Trading
Connect the picture to the technical model
The operator workspace is the organization selected by the tenant authority. The buying company is the customer account. A seat joins a user to an account with account_role=owner or member. Domains and branding belong to the operator organization, not independently to each customer account.
02 / One account at a time
Ana changes context, not identity.
She owns Acme’s account and has an accepted seat in Beta’s. An authorized switch replaces the account context used by her app session.
Ana in Acme
{ "sub": "ana", "account": "acme", "account_role": "owner" }The app opens Acme’s records and checks Ana’s owner permissions.
Ana in Beta
{ "sub": "ana", "account": "beta", "account_role": "member" }The app opens Beta’s records and checks Ana’s member permissions.
Illustration only: these controls make no account or authentication request.
How a real account switch works
The .NET SDK’s POST /switch-account uses the current refresh session, verifies the live seat and replaces the cookie with newly validated claims. A browser-supplied account ID alone is never permission. Clear or reload account-specific app state after a switch.
03 / A different door, a different role
Maya can use her own product as a customer.
Running Field Notes and using Field Notes are different contexts. Her staff authority belongs in the administration console.
PLATFORM CLIENT
Administration console
Staff or organization-admin authority.
org_role: workspace:org_adminCUSTOMER CLIENT
Field Notes app
Her selected customer account and its seat role.
account_role: owner | member04 / A bigger business
What if Ana builds a product too?
Ana can obtain an operator workspace of her own while remaining Maya’s customer. Her new workspace has its own products and policies; owning it grants no extra access inside Maya’s.
Maya’s workspace
Ana is a customer in Field Notes.
Customer account and seatAna’s workspace
Ana runs her own product and team.
Operator authorityPlatform login and organization handoff
The platform directory knows the workspaces available to the person. A short-lived, single-use handoff establishes a session in the chosen organization. Product OIDC establishes the product’s own session. Existing sessions can avoid another password prompt; MFA, consent or account choice may still require interaction.
A master token has a separate audience and token purpose. It is not accepted as a customer API bearer token.
Session boundaries →05 / Your brand, all the way back
The login is a visit. Your app is the destination.
Field Notes
Ana chooses Sign in.
Sign in to Field Notes
Acme’s Field Notes
The validated callback opens the intended product context.
Callbacks, Home URL and safe return destinations
Register exact HTTPS callback URLs, configure branding and HomeUrl, and retain the originating client through hosted email and recovery continuations. Arbitrary return URLs are not trusted. A plain redirect back to the product is not itself an OAuth callback.
The dedicated customer-team flow restricts return origins to the exact managed client’s callbacks. Do not assume all hosted surfaces share the same return policy.
White-label setup and return rules →06 / Consent has a lifecycle
An invitation is a question before it is a seat.
The enforcement window depends on the credential: cookie revalidation and refresh checks differ from a signed bearer token that remains valid until expiry.
Customer teams and owner-authorized invitations →