Skip to main content

App roles

App roles let you give some users more power inside your app, such as approving purchase requests or editing every row, without building role tables yourself. You name the roles, assign them to people or directory groups, and the platform delivers them with every request.

Define and assign roles​

  1. Open the project and select Access.
  2. Under App roles, type a name in New role name (for example approver) or pick a suggested one.
  3. In Give "approver" to people or groups…, search the directory and add people or groups.
  4. Select Save changes.

Role names use lowercase letters, digits, _, - and ., start with a letter, and are at most 40 characters.

You can also set roles with the MCP tool set_access, or with PUT /api/projects/<name>/access on the Hub API. Fields you leave out keep their current values; roles, when present, replaces the whole role map:

{
"mode": "groups",
"members": ["Operations"],
"roles": { "approver": ["henrik.larsen@contoso.com"] }
}

Rules​

  • The owner holds every role. It's their app.
  • A role implies access. In every mode except Only me, a role holder can open the app even if they aren't otherwise covered by the access setting.
  • Groups work. Assign a role to a directory group and every transitive member holds it.

Reading roles in your app​

WhereHow
The X-TC-User tokenroles claim, an array of role names. See Verify the user's identity.
The browserGET /_tc/auth/me returns the user with roles
The SDKconst me = await tc.auth.user(req), then me.roles.includes('approver') or me.hasRole('approver')
SQL row-level securitytc.has_role('approver')
create policy "approvers can update"
on purchase_requests for update
using (tc.has_role('approver'));

Roles with platform meaning​

Most role names mean whatever your app decides. Three have extra meaning on the platform:

RoleExtra meaning
developerProject developer: can deploy, change access and environment variables, and use the Database Studio. See Project permissions.
editor, adminIn private storage buckets, can replace or delete anyone's files. See Data.

Teams notifications can target a role with to: 'role:approver'. See Microsoft Teams.

Was this page helpful?