Configuring OAuth Settings in Tokity

Helpdocs Admin Updated by Helpdocs Admin

This page covers the tenant-wide OAuth settings available under Advanced → Open Authorization → Settings. These settings apply across all apps for a given scenario, and directly affect security posture — so it's worth understanding what each one does and why it exists before changing it.

Issuer Host

The Issuer Host value is used as the iss claim in every OAuth token issued by your tenant. It's auto-populated by default, and can be changed to a custom domain if needed.

This should be treated as an infrastructure setting, not a branding opportunity. Nobody consuming your tokens is inspecting the iss claim and forming an opinion about your custom OAuth implementation — it's purely a technical identifier that downstream systems rely on to verify where a token came from. The realistic reason to change this is a rare, specific scenario: your organization is changing DNS and needs the issuer to reflect a new domain. Outside of that, keep the system default. Changing it without a real reason just adds risk of inconsistency — if the issuer host changes while tokens referencing the old one are still in use, verification can break for anything relying on that value staying stable.

System-wide, Agent, and Contact Authorization

Tokity has three separate configuration areas — System Wide API Access, Agent Authorization, and Contact Authorization — each governing one of the three grant targets covered earlier in OAuth Basics. Each of these three areas exposes the same two settings, configured independently, so you can tune each scenario differently based on its risk profile:

Authentication Policy — controls whether a client secret is required for that scenario:

  • Require client secret for all applications — no app in this scenario can authenticate without a secret, regardless of how the individual app is registered.
  • Allow applications to authenticate without a client secret — apps registered as public for this scenario can skip the secret, per the rules covered in Confidential vs. Public Apps & Client Secrets.

Refresh Token Lifetime — how long a refresh token remains valid before it must be re-issued, from 1 to 28 days, defaulting to 14 days. Generally, shorter is more secure — it limits how long a stolen refresh token stays useful — but the right value depends on whether the integrator on the other end can reliably handle re-authentication at that frequency. Setting this too short for an integration that can't keep up may cause it to silently lose access more often than intended.

In addition to these two shared settings, Agent Authorization and Contact Authorization each have a Who Can Grant Consent setting, controlling who is allowed to approve a personal consent grant for that group:

  • Agent Authorization: Self or Master Admin, or Master Admin Only.
  • Contact Authorization: Self or Admin, or Admin Only.

This determines whether the individual (agent or contact) can approve their own personal grants, or whether that approval must always go through an administrator.

Why three separate configurations?

Splitting these settings by target (system-wide, agent, contact) exists to give you maximum flexibility: a policy that makes sense for tightly controlled system-wide automation isn't necessarily right for individual agent or contact grants, and vice versa. It's fine — and expected — for these to differ from each other, as long as each is set deliberately for its own use case rather than copied from one to another without thought.

How did we do?

Managing OAuth Authorized Sessions and User Consent

Contact