Roles & Scopes

Helpdocs Admin Updated by Helpdocs Admin

Access to the Toki Iti API is controlled by two layers working together: an agent's role, and — when accessing the API via API key or OAuth — scopes. Roles define what a person can do inside our UI; scopes define what an integration is allowed to do on that person's behalf.

Agent roles

Toki Iti has two kinds of users, stored in separate tables: Agents (internal staff) and Contacts (end customers). Agents are assigned one of four roles, each building on the one before it:

Role

Description

Agent

Base role for standard technicians

Advanced Agent

Group leader — for organizations with a "small manager" layer above base agents

Admin

Manages Client Portal settings — e.g., which queues contacts can access, branding, etc.

Master Admin

Full tenant-level control — email connectors, delivery settings, API keys, OAuth settings, and more. Think of this as the tenant's "owner" or web administrator.

All TECH Portal API access is both role-bound and scope-bound — a request needs the right role and the right scope to succeed.

What are scopes?

Scopes are a newer addition that work alongside roles, adding a second axis of control. While a role determines what an agent can do in our UI, a scope determines what an integration — connecting via API key or OAuth — is allowed to do on that agent's behalf.

Every agent inherently has access to everything their role allows. But when an integration connects on their behalf, scopes narrow that down to exactly which resources and actions the integration is permitted to use. In short: roles govern people, scopes govern integrations.

Scope naming pattern

Most entities expose scopes using a read, read_write, and occasionally admin suffix:

  • agent:read
  • agent:read_write
  • agent:admin

The admin suffix is rarely used to gate an entire endpoint. It's more commonly used to gate specific properties within an entity. Some properties can only be modified by users with Admin or Master Admin roles — scopes let a tenant grant an integration limited write access (read_write) without exposing those higher-privilege fields (admin).

Are restricted properties still returned?

Yes, always. These properties are typically permission-related (e.g., which queues someone can access), and returning them has no performance cost — we're not querying a traditional SQL database under the hood. Being able to see a permission doesn't mean you can see the data it governs (e.g., you still can't see tickets you don't have access to). Scope restrictions on these properties apply only to write operations, and only for a handful of entities.

Where scopes come into play

You'll see required scopes listed directly in each endpoint's description in Swagger. Scopes matter most when:

  • You're creating an API key and choosing which scopes to grant it.
  • You're setting up an OAuth app and a user is asked to consent to specific scopes.

👉 See Authorization Options for how scopes are applied when using API keys vs. OAuth.

Where to go next

How did we do?

API Versions & Routes

Authorization Options

Contact