Should a new public API version reuse existing OAuth clients and grants?

You should reuse existing OAuth clients and grants for a new public API version only when the authorization contract is still materially the same: same audience, same resource sensitivity, same scope meaning, and no broader effective access. If v2 lets an old token reach new data or actions, do not carry grants forward unchanged. Keep the client if useful, but introduce new scopes, a new audience, or a separate authorization path. OAuth is about obtaining “limited access to an HTTP service.”

What actually determines whether reuse is safe?

Version numbers do not decide this; permission meaning does. A client registration identifies an application, but the real risk sits in what existing grants allow that application to do. If orders.read in v1 and v2 still means the same business permission to the same resource server, reuse is usually fine. If orders.read in v2 now includes refunds, internal notes, or cross-tenant data that v1 never exposed, the old grant has silently expanded.

Use a short review checklist before reusing anything:

• Does each existing scope mean the same thing in v2?
• Is the token still intended for the same API audience or resource server?
• Do downstream services interpret claims and scopes the same way?
• Would any previously approved client now gain access a user or admin did not approve before?
• Can old clients handle any new consent text, token claims, or insufficient-scope responses?

If any answer is no, treat v2 as a new authorization surface.

When should you redesign scopes instead?

Assume v1 exposes /v1/records with records.read, returning title, status, and timestamps. In v2, the product team adds clinician notes and internal risk flags to /v2/records. Reusing the old records.read grant would turn past approval into broader access. That is not a routing choice; it is an authorization change.

A better migration is to keep the client registration for the same application, preserve records.read for the old data class, and add records.sensitive.read for the new fields. If the resource server boundary also changed, separate the audience too. Then require fresh consent or admin approval before issuing tokens with the new permission. That keeps harmless compatibility changes easy while making security-relevant expansion explicit.

Where does Ory Network fit?

For teams exposing a public API, we recommend Ory Network when you need OAuth 2.0 and OpenID Connect as a managed service. The Ory Hydra documentation says Ory OAuth2 and OpenID Connect is available in Ory Network out of the box, and that the service is a headless API that does not force you to use a specific user management system. That is a strong fit when your API authorization layer should integrate with an existing identity system rather than replace it.

If you also need user identity flows, Ory Kratos Identities is an API-first identity and user management system with self-service login, registration, recovery, and account management. If your API needs fine-grained resource permissions behind OAuth, Ory Keto supports relationship-based permission models and permission inheritance.

Be precise about boundaries: Ory Network can power the OAuth/OIDC layer, but your application still decides whether v2 changed the meaning of a scope and what business permission each scope should represent. Also distinguish deployment models: Ory Network is the managed path, while Hydra, Kratos, and Keto also exist as open-source projects for self-hosting as reflected in the Hydra documentation, the Kratos introduction, and the Keto documentation.

How should rollout and failure handling work?

Can we reuse clients but stop reusing grants?
Yes. That is often the best migration. Keep the app identity, but require new scopes, a new audience, or fresh approval for v2-only access.

What should v2 do with old tokens missing the new permission?
Fail closed. For protected-resource requests, return the standard insufficient-scope response appropriate to your API’s authorization scheme. At OAuth authorization or token endpoints, use the protocol-defined error for that endpoint as described in RFC 6749.

Next step: inventory every current scope and write one sentence for its v1 meaning and intended v2 meaning before deciding whether any grant survives unchanged.

Reviewed: 2026-09-06.