Roles & Access Context

Every embedded surface load carries two pieces of access information in the Marketplace handshake: the user's partner roles and an access context. This guide explains where each comes from, how Hint decides them, and what your app is required to do with them.

How roles reach your app

Role assignment is controlled entirely on the Hint side. You declare the roles your app supports; Hint resolves which of those roles a given user has and includes them in the handshake payload as user.partner_roles (an array of role-name strings). Your app never manages role assignment itself - it reads partner_roles and applies its own in-app RBAC.

{
  "user": {
    "id": "user-BtAH8TTXCo6P",
    "email": "[email protected]",
    "partner_roles": ["admin"]
  },
  "access_context": "standard"
}

📘

Roles live in the handshake, not the JS SDK

partner_roles and access_context are delivered in the signed server-to-server handshake payload only. They are not exposed on HintSDK.user in the browser. Read them on your server when the handshake arrives and persist them with the session.

Configuring your roles

You declare your app's roles through your App configuration (PATCH /partner/products/:id/app). Each role has:

• name - the identifier sent in partner_roles (e.g. admin, member).
• description - a short, human-readable explanation of what the role can do (e.g. "Full access including billing configuration and user management"). Hint surfaces these descriptions to the practice admin during install and in the practice's App Settings, so they understand what each role grants.

Alongside the role list you also declare:

• admin role - which of your roles is the admin equivalent. Practice admins are mapped to this role, and it is the role sent for Hint platform-support sessions (see below).
• suggested default role - the role pre-selected for non-admin practice users.
• default access posture - whether Hint should pre-populate the practice's role mappings with your suggested admin and default roles on install, or start the practice at "no access" so they configure mappings manually.

How Hint assigns roles

Hint resolves a user's roles with the following precedence:

1. Explicit assignment - if a practice admin has assigned a specific role to a user in the app's user table, that role always wins.
2. Role mapping - otherwise Hint looks up the user's type (practice admin or non-admin) and applies the practice's configured mapping for that type. When auto-grant is enabled, this mapping is applied automatically to team members as they are added to the practice.
3. No role - if neither applies, the user has no partner roles and partner_roles is an empty array.

The installing admin is assigned your admin role at install time, so they can use and configure the app the moment installation completes.

Handling users with no role

When a user has no resolved role, Hint still loads your surface but sends an empty partner_roles array. Treat this as "no access": render a clear, actionable state - for example, "You do not have access to this application. Please contact your practice admin to get access." - rather than erroring out.

access_context - required capability

Every handshake includes an access_context attribute describing what kind of session it is:

{
  "user": { "id": "user-9dQ2rk", "email": "[email protected]", "partner_roles": ["admin"] },
  "access_context": "platform_support"
}

platform_support sessions occur when a Hint employee opens your surface to help a practice - for example, when a practice reports a support issue to Hint, or when a Hint team member is training a practice on your app. This is delegation, not impersonation: the Hint employee is acting in their own capacity as a platform operator, not pretending to be a practice user. The role sent alongside is always your designated admin role, so support has full visibility.

access_context is session metadata, not a role. Your app must handle platform_support sessions distinctly from standard ones:

• Do not provision a persistent user in the practice's account for the session. These sessions are ephemeral. Treat them the way you treat a session from your own support team - store session state only, keyed by the practice, and do not create a customer user record from the handshake user.
• Scope access to that practice with admin-level (or read-only, if your product prefers) visibility. Do not expose data from other practices.
• Attribute audit-log entries to a platform-support session, not to a customer user, so your logs distinguish vendor-initiated access from customer activity.
• Surface a visible indicator, such as a "Hint support session" banner, so it is clear the account is being viewed by Hint.

🚧

Why this matters

In healthcare, vendor access to a customer's environment carries specific BAA and compliance implications. Distinguishing platform-support sessions from customer sessions keeps audit trails accurate and access appropriately scoped.

Decode the handshake permissively: access_context may gain additional values over time (e.g. other platform contexts), so treat any unrecognized value as non-standard and default to your most conservative handling.