Understanding OAuth for Tokity Integrations: Key Concepts

If you've used the Tokity API before, you're probably familiar with API keys: a static credential that grants access based on a fixed set of scopes. OAuth works differently. Instead of a long-lived secret you manage yourself, OAuth is built around a consent-based, time-limited authorization model — a user (or an admin, on behalf of the tenant) explicitly grants an application permission to act on their behalf, and that permission can be reviewed, reduced, or revoked at any time.

Why choose OAuth over an API key?

OAuth can operate at the same system-wide level as an API key, but it can also operate at a personal level — tied to a specific agent or contact. That variety alone is one reason to consider it. Two other reasons stand out:

Security. With an API key, the credential itself is the thing that has to stay secret. If it leaks, it's valid until someone rotates or revokes it. With OAuth, as long as a session keeps using its refresh token, the session can continue indefinitely — but the actual access token in use only lives for 1 hour, and the underlying signing keys are rotated every 7 days. There's no static, long-lived secret sitting in a request header waiting to be replayed, and no need for the "rotate your API key periodically" hygiene that comes with static credentials.

Visibility and maintainability. Each authorized session is tracked individually, so you can see exactly what's connected, when it was last used, and revoke it on its own — without affecting anything else. API keys don't offer that same context. It's common for a single API key to end up shared across several projects, and over time it becomes unclear which project depends on it — making any change or rotation risky, since you're never quite sure what might break.

OAuth is a well-defined contract, but it's not a simple one — that's the honest trade-off for the benefits above. Most developers rely on an OAuth library to handle the handshake, rather than implementing the flow from scratch, so you don't need to master every detail of the protocol to use it effectively. This article won't make you an OAuth expert in five minutes — that usually comes with hands-on implementation — but it will introduce the two building blocks you'll see everywhere else in these docs: authorized sessions and consent grants.

Getting started, depending on your use case

How much of OAuth you need to actively manage depends on what you're building:

• Automation (no-code / low-code tools). In most cases, you simply fill in the required OAuth information and let the automation platform maintain the session for you — including refreshing it. Your main job is knowing what information to provide.
• A dedicated project in a programming language. You'll typically use an OAuth library for your language rather than implementing the handshake yourself. Like automation setups, you'll fill in the required OAuth information, but you're also responsible for maintaining two additional pieces:
  • Client secret — store this in a secret manager (such as a key vault), not in code or config files.
  • Refresh token — store this somewhere secure as well, along with the scopes and other details you'll need to exchange it for a new access token.

Authorized sessions

An authorized session is created the moment a user grants consent to an application. It represents an active, ongoing authorization — the "instance" of an app being connected to a user's (or the tenant's) data.

Sessions are inherently temporary:

• The access token issued within a session is only valid for 1 hour.
• If your application isn't using a refresh token, the session exists only long enough to support that short window — a few days at most, mainly useful for diagnostics.
• If a refresh token is used, the session's lifetime extends further, and each time the refresh token is used, the session's lifetime extends again. Used consistently, a session can effectively persist indefinitely, until the session or its consent grant is revoked.
• If a session is never refreshed or renewed, it's automatically removed by the system once it expires.

In short: a session stays alive only as long as your application keeps using it. Stop using it, and it eventually expires on its own — no manual cleanup required.

Consent grants

A consent grant answers a different question than a session does. Where a session represents "this app is currently connected," a consent grant represents "this application is allowed to do this."

Key differences from a session:

• A consent grant is usually created at the same time as an authorized session (when a user grants access). However, an admin can also create one ahead of time — this is known as an admin grant, and it's covered in more detail in a later article.
• Unlike sessions, a consent grant doesn't expire on its own. It lasts until it's explicitly revoked or reduced.
• A consent grant tracks approvals across multiple sessions over time, and keeps only the highest equivalent scope rather than a growing list. For example, if account:read and account:read_write are both granted, the grant simply keeps account:read_write.

Consent can be granted at different levels — for an individual agent or contact ("personal consent"), or for the tenant as a whole ("system-wide consent," typically used for automation, such as reacting to a webhook and updating a ticket without depending on any one user). We'll cover exactly how these levels work, and how they interact, in Admin Consent at Root Level.

Scopes: OAuth vs. API key

At the system-wide level, OAuth scopes are the same as API key scopes — the two share the exact same scope list. The one difference between a system-wide OAuth grant and an API key is that OAuth also supports the offline_access scope, as defined by the OAuth specification — this is what enables refresh tokens, and it has no equivalent for API keys.

Personal grants (tied to a specific agent or contact) work differently. They don't include the small set of scopes reserved for system-wide use (such as the Power Automate connector, or acting on behalf of an agent/contact) — those only apply when acting on behalf of the tenant as a whole, not a specific person. Instead, what's available to a personal grant differs by user type:

• Agents have access to a much broader set of scopes.
• Contacts are scoped mainly to the client portal — largely read access to things like menus and the service catalogue, plus the ability to modify tickets and their own data.

Personal grants also support standard OpenID Connect scopes (openid, profile, email), used to verify who the user is.

We'll go into the full scope list and what each one unlocks in a dedicated article — for now, the main thing to know is that OAuth scopes are managed the same way as API key scopes, through the same UI.

What's next

Now that you know what authorized sessions and consent grants are, the next step is understanding how a user actually grants that consent — see Code Authorization Flow for a walkthrough of the supported OAuth flows, including OpenID Connect.