Skip to main content

Roles

Roles are named groups that users belong to. Use roles to control who can access your data and perform specific operations.

User Context​

The Current User Context control in the sidebar affects what data you see in Users & Roles. By default, System user is selected with "Skip roles" enabled, giving full access. Change the user context to test what different users would see based on their permissions.

Built-in Roles​

Every API includes these system roles that cannot be modified:

JSON SchemaPortal NameDescription
_EVERYONEAnonymous userPublic access — no authentication required
_AUTHENTICATED_USERAuthenticated userAny logged-in user
_CREATOROwnerThe user who created the record
note

The Developer Portal displays user-friendly names (e.g., "Anonymous user"), while the JSON schema uses technical identifiers (e.g., _EVERYONE). Use the JSON schema names when writing access rules in code.

Managing Users​

The Users tab shows all users in your API with their authentication details.

User Information​

Each user displays:

  • Name — User's display name from their identity provider
  • Provider — Logo/icon showing which identity provider they authenticated with (Google, Microsoft, Apple, etc.)
  • Email — User's email address
  • Roles — Assigned role memberships

Service accounts appear in the list too, marked with a bot icon and a service account badge. They hold roles like any other user, but their lifecycle (name, secrets, deletion) is managed on the Access page — the edit and delete actions are disabled for them here.

  • Sort users by any column
  • Use server-side sorting for large user lists
  • Search by name, email, or ID

Custom Roles​

Create custom roles to match your application's permission model.

Creating a Role​

  1. Sign in to the Developer Portal
  2. Navigate to your API
  3. Go to Users & Roles → Roles
  4. Click Create Role
  5. Enter a role name (e.g., "editor", "viewer", "moderator")

Managing Members​

Expand a role to see and manage its members.

Add users to a role:

  1. Expand the role row
  2. Click Add Members
  3. Select users to add

Remove users from a role:

  1. Expand the role row
  2. Click the delete icon next to the user
Role names are unique

Role names are unique within an API (case-insensitive) — in a Business tenant, unique across the whole tenant, since all linked APIs share one role set. Access rules reference roles by name, so a duplicate would make them ambiguous; attempts to create or rename into an existing name are rejected.

Roles in Business Tenants​

In a Business tenant, all non-public APIs share a single set of users and roles, owned by the tenant's master API (see Linked applications). Roles come in two flavours there:

Tenant-wide roles​

Roles created on the master API exist for the whole tenant: every linked app sees them, can reference them in its access rules, and their members carry them everywhere. Tenant-wide roles — and their memberships — are managed on the master, by tenant administrators. On a linked app they appear with an inherited badge and are read-only.

App-scoped roles​

A linked app can also create roles of its own. A role created from a linked API is scoped to that app:

  • Created and managed locally. Anyone with contributor access to the app can create, rename, and delete its scoped roles and manage their members — no tenant-admin rights needed. Scoped roles show a this app badge.
  • Members can be any user of the tenant — end users and service accounts alike. The membership itself is tenant-shared (it's the same role table), but the role only means something where it's referenced.
  • Invisible to sibling apps. A scoped role doesn't appear in other linked apps' role lists or access-rule editors. The master sees all scoped roles, labelled with their owning app, and tenant administrators can manage them from there too.
  • Enforced like any role. Reference a scoped role in the owning app's access rules exactly as you would any custom role.
Scoped roles and application access

If the owning app already gates access by role, a newly created scoped role is automatically enabled on that app's application access allow-list, so its members can open the app. If the app's allow-list is empty (open to all authenticated users), it stays that way — creating a role never switches the gate on. Likewise, deleting a role never removes the last entry from an app's allow-list, so a gated app can't silently fall open.

note

A scoped role can't be used as an identity provider's default role — providers are tenant-wide, so their default role must be too.

Role Assignment​

Users can have roles at two levels:

Global Roles​

Assigned at the API level. Global roles apply across all collections and views.

Use cases:

  • Admin users who need full access
  • Moderators who need broad permissions
  • Service accounts with specific capabilities

Local Roles​

Assigned within specific collections through data relationships. Local roles provide row-level access based on user data.

Use cases:

  • Project members who can only access their assigned projects
  • Team leads who can manage their team's data
  • Users who can only access their own records

Role Priority​

When evaluating access:

  1. Global roles are checked first
  2. If no global role grants access, local roles are checked
  3. Access is granted if any matching role permits the operation

Best Practices​

  • Start restrictive — Begin with minimal permissions and add as needed
  • Use descriptive names — "content_editor" is clearer than "role1"
  • Prefer roles over individual access — Easier to maintain
  • Document your roles — Keep track of what each role is meant for
Last updated on