OAuth Personal Secrets: What They Are and When to Use Them

Helpdocs Admin Updated by Helpdocs Admin

A personal secret is, functionally, a client secret — used the same way, at the same token endpoint, via client_secret_post or client_secret_basic. The difference is scope: rather than belonging to the application as a whole, a personal secret is tied to one person, for one specific app. It exists so an individual agent (or, in future, contact) can authenticate their own personal grant, without relying on — or being able to access — the application's shared client secret.

This isn't a concept defined in the OAuth specification itself; it's a scoping model Tokity has added on top of standard client secrets, mainly to reduce the blast radius if a secret ever leaks (see Confidential vs. Public Apps & Client Secrets for more on that).

Why personal secrets exist

Personal secrets were introduced largely with AI tooling in mind — specifically, tools like local MCP connectors, where a user runs their own instance of a client (either in a personal environment, or through an AI model provider) that needs to connect to Tokity directly.

These setups don't always fit neatly into the usual "one app, one shared secret, managed centrally" model:

  • If your organization can configure the OAuth setup centrally on the user's behalf, the standard application client secret is the right approach — this is the normal case.
  • If it can't — for example, a user running their own local MCP connector, where each person has to fill in their own OAuth configuration individually — a personal secret lets that person authenticate their own personal grant without needing access to the application's shared client secret.

Only a master admin can create an app registration in the first place, so in many cases a master admin may simply fill in the required OAuth configuration for users, which reduces how often personal secrets are actually needed in practice. Whether personal secrets remain useful largely depends on how a given tool (like a specific MCP connector) is designed — how much configuration it expects the individual user to provide themselves.

Note: This is a newer, narrower use case, and we're still evaluating how much it's actually used in practice. If it doesn't see meaningful adoption, this feature may be revisited or removed in the future.

Where to create one

Personal secrets are currently managed from the Admin Portal (agents only — contact support is planned as this becomes available for contacts too):

More / Settings / Connected Apps / Platform Apps or Organization Apps

From there, select the relevant app — platform or organization — and create or manage secrets under it.

Note: The Admin Portal is in the process of being merged into the TECH portal. Once that's complete, this same functionality will be available under the TECH portal's own navigation instead.

You don't need an existing consent grant to create a personal secret — the two are independent. In practice, you'll usually create the secret before connecting the app, since it's one of the values you'll need to fill in alongside the authorize, token, and refresh links when configuring the integration on the other end.

Limits and expiry

  • Each person can have up to 3 secrets per app at a time — useful if you need to roll a secret without downtime, by creating a new one before removing the old.
  • Every secret has an expiry, chosen at creation time, up to a maximum of 24 months:
    • 90 days (3 months)
    • 180 days (6 months) — recommended
    • 365 days (12 months)
    • 545 days (18 months)
    • 730 days (24 months)

These same expiry options apply to application-level client secrets as well, not just personal ones.

Removing a secret

Removing a personal secret doesn't cut off an active session immediately, but it does prevent that secret from being used again. In practice, this means any integration still relying on it will stop being able to refresh its token — so access typically ends within about an hour, once the current access token expires and the refresh attempt fails.

What's next

With app registration, client secrets, and personal secrets covered, the next section moves into OAuth Administration — how sessions and consent grants are viewed and managed, and how admin-level and global settings work.

How did we do?

Choosing an OAuth App Type: Confidential vs. Public Apps and Client Secrets

Contact