Granting OAuth Admin Consent at the Root Level

Helpdocs Admin Updated by Helpdocs Admin

Root-level consent only applies to personal grants — there's no equivalent concept for system-wide consent, since system-wide access is already a single tenant-level grant with nothing underneath it to layer on top of.

The two hierarchies

Since Tokity is an ITSM system, contacts and agents are structured differently:

  • Agents have no grouping above them. The only root level available is TECH portal.
  • Contacts always belong to a single account (a branch, company, or team, depending on how the system is used). Because of this, contacts have two levels above the individual: Client Portal (tenant-wide root) and Account (specific to contacts under that one account).

How the levels combine

For a contact, the effective root-level scope is resolved like this:

  • Client Portal is the tenant-wide default for all contacts.
  • Account, if configured, completely replaces Client Portal for contacts under that account — it's a full substitution, not a merge between the two. Whichever one applies (account if set, otherwise client portal) becomes that contact's effective root scope.
  • The contact's individual grant is then unioned with that effective root scope — the individual grant can only add scopes, never take any away.

For agents, it's simpler: TECH portal root, unioned with the individual agent's own grant.

Why account-level is an override, not a union

Account-level exists specifically so you can make an account different from the tenant default — most commonly, more restrictive. For example, if you want to reduce a specific account's exposure to a tool, or block it from using a tool entirely, you can grant that account fewer scopes than the Client Portal root — down to none at all. This only works as an override, because a union would make it impossible to ever grant an account less than the tenant-wide default; the account setting would only ever be able to add access, never restrict it.

One consequence worth knowing: if Client Portal already grants a scope and a contact is actively using it, introducing (or narrowing) an account-level override with less scope can end that contact's active session — their access is recalculated against the new effective root, and if the scope they relied on is no longer there, their session is no longer valid.

Why individual is a union, not an override

This part isn't unique to Tokity — it mirrors how most OAuth-based admin consent models work (for example, Microsoft Graph's admin consent behaves the same way). Root-level consent sets a baseline, and an individual can still request additional scopes on top of it. If individual grants instead overrode the root, requesting one extra scope could accidentally strip away everything the root already provided — which isn't the intent. Union avoids that: it only ever adds, never removes.

Why account-level is an override — Tokity's addition

This is where Tokity diverges from the typical admin-consent pattern. Because a contact always belongs to an account, and different accounts often need their own distinct access profile — not just a smaller version of the tenant default, but potentially a different shape entirely — account-level consent is designed as a full override rather than a union.

A union could only ever add to the Client Portal default, never reshape it. An override lets an account be configured independently: it can shrink scope, shrink and swap in different scopes entirely, or grant something the tenant default doesn't include at all. That flexibility — giving an account its own consent "personality," rather than just a restricted subset of the tenant's — is exactly what a union relationship can't provide.

Root-level consent (TECH portal, Client Portal, or account) exists for two main reasons:

  • It keeps access working even when individual grants are turned off. If self-service consent has been disabled (see OAuth Global Settings, "Who Can Grant Consent"), individuals can no longer grant their own consent — but an admin or master admin can still grant the required scopes at the root level, so everyone under that root keeps working without needing an admin to grant consent one person at a time. A common example: making sure an organization can keep using an AI/MCP connector even after individual consent for it has been revoked.
  • It simplifies the process for everyone. When a root-level grant already covers what an application needs, an individual connecting to that app skips the authorize/consent screen entirely — the flow redirects straight to the application. This is worth keeping in mind even when self-service consent is fully enabled: root-level grants aren't only a fallback for when individual consent is turned off, they're also a way to make the everyday experience of connecting an app smoother.

How did we do?

Managing OAuth Authorized Sessions and User Consent

Contact