Authorization Options

Helpdocs Admin Updated by Helpdocs Admin

There are two ways to authorize access to the Toki Iti API: API keys and OAuth. Both let you control access using scopes, but they differ in how they're set up, managed, and monitored.

API Key

API keys are the simpler of the two options and come in two forms:

  • System-level API key — grants tenant-wide access, with fine-grained scopes you choose at creation. No per-user access restrictions apply — it can reach any queue, account, or ticket category.
  • Personal API key — created by an individual agent (contact support for this isn't available in the UI yet). It grants access to both the TECH Portal and Client Portal APIs, but is limited to that user's own permissions — the same queue, account, and ticket category restrictions that apply to them normally.
Limits
  • Up to 50 personal API keys per agent or contact.
  • Up to 50 system-level API keys per tenant.

Personal limits are generous for individual use, but the system-level limit is worth planning around if you're managing multiple integrations for a tenant.

OAuth

OAuth is our newest authorization method and the first place we introduced scopes for every API endpoint — you can see each endpoint's required scope directly in its Swagger description.

OAuth access comes in two forms, matching the same pattern as API keys:

  • System-wide OAuth grant — similar in effect to a system-level API key.
  • User-level OAuth grant — authorized on behalf of a specific agent or contact, and restricted to that user's own permissions.

OAuth is more complex to set up and understand than an API key, but it comes with much stronger traceability. Through our UI, tenants can:

  • See exactly which applications have been granted access, by whom, and when.
  • Check whether a connection is still active or has been used recently.
  • Revoke access, or adjust the scopes granted to an app, at any time.

Because OAuth app registration is open, customers can register an app for each specific use case — giving them more visibility and control over what's connected to their tenant than a shared API key typically allows.

API Key vs. OAuth — which should you use?

API Key

OAuth

Ease of use

Simple, widely understood

More complex to implement and understand

Traceability

Limited

Full visibility — see who granted access, to which app, when, and whether it's still active

Control

Scopes set at creation

Scopes can be viewed, revoked, or adjusted at any time

Limits

50 personal keys per agent/contact; 50 system-level keys per tenant

No fixed connection limit

Rule of thumb:

  • Use an API key for quick, ad-hoc integrations where simplicity matters most.
  • Use OAuth when you need finer-grained control, stronger security practices, and full visibility into what's connected to your tenant.

How did we do?

Roles & Scopes

Querying the API

Contact