feat: Docs for client secret rotation #2424

SamuelDev · 2026-01-23T17:17:31Z

Checklist

I have read the contributing guidelines and signed the CLA.
I have referenced an issue containing the design document if my change introduces a new feature.
I have read the security policy.
I confirm that this pull request does not address a security vulnerability.
If this pull request addresses a security vulnerability,
I confirm that I got approval (please contact security@ory.com) from the maintainers to push the changes.
I have added tests that prove my fix is effective or that my feature works.
I have added the necessary documentation within the code base (if appropriate).

Further comments

SamuelDev · 2026-01-23T17:37:58Z

Javascript integration test failure seems like a CI issue and unrelated to these changes

alnr · 2026-02-11T15:26:29Z

@wassimoo @unatasha8 would you kindly take a look at this pls?

vinckr

lgtm :) fixed some layout issues

unatasha8 · 2026-02-12T18:30:59Z

docs/hydra/guides/oauth2-clients.mdx

+## Rotate OAuth2 client secret
+
+OAuth2 client secret rotation allows you to change a client's secret without downtime. When you rotate a secret, the old secret
+remains valid until you explicitly clean it up, allowing you to update all services using the client credentials without service


Suggested change

remains valid until you explicitly clean it up, allowing you to update all services using the client credentials without service

remains valid until you remove it, allowing you to update all your services without service

unatasha8 · 2026-02-12T18:32:13Z

docs/hydra/guides/oauth2-clients.mdx

+
+##### How secret rotation works
+
+1. Rotate the secret: Generate a new secret for the client


Suggested change

1. Rotate the secret: Generate a new secret for the client

1. Generate a new secret for the client service

unatasha8 · 2026-02-12T18:33:35Z

docs/hydra/guides/oauth2-clients.mdx

+##### How secret rotation works
+
+1. Rotate the secret: Generate a new secret for the client
+2. Both secrets work: Old and new secrets both authenticate until cleanup


This should be #3 not #2. The new secret won't work until you update the client application, right?
Move position and change to: "Both old and new secrets authenticate until you remove the old secret."

unatasha8 · 2026-02-12T18:34:17Z

docs/hydra/guides/oauth2-clients.mdx

+
+1. Rotate the secret: Generate a new secret for the client
+2. Both secrets work: Old and new secrets both authenticate until cleanup
+3. Update services: Update your applications to use the new secret


Suggested change

3. Update services: Update your applications to use the new secret

3. Update your client services to use the new secret

unatasha8 · 2026-02-12T18:36:57Z

docs/hydra/guides/oauth2-clients.mdx

+1. Rotate the secret: Generate a new secret for the client
+2. Both secrets work: Old and new secrets both authenticate until cleanup
+3. Update services: Update your applications to use the new secret
+4. Cleanup: Manually remove old rotated secrets once all services are updated


Suggested change

4. Cleanup: Manually remove old rotated secrets once all services are updated

4. After you test the client services can authenticate with the new secret, manually remove the old secret.

unatasha8 · 2026-02-12T18:42:33Z

docs/hydra/guides/oauth2-clients.mdx

+
+##### Clear rotated secrets
+
+Once all services have been updated to use the new secret, you can remove the old rotated secrets to revoke access using the old


Suggested change

Once all services have been updated to use the new secret, you can remove the old rotated secrets to revoke access using the old

Once all services are updated to use the new secret, remove the old secret to revoke access using the old

unatasha8 · 2026-02-12T18:42:50Z

docs/hydra/guides/oauth2-clients.mdx

+##### Clear rotated secrets
+
+Once all services have been updated to use the new secret, you can remove the old rotated secrets to revoke access using the old
+credentials:


Suggested change

credentials:

secret:

unatasha8 · 2026-02-12T18:44:07Z

docs/hydra/guides/oauth2-clients.mdx

+  -H "Authorization: Bearer ory_pat_..."
+```
+
+After cleanup, only the current secret will be valid. Old secrets will no longer authenticate.


Suggested change

After cleanup, only the current secret will be valid. Old secrets will no longer authenticate.

After removing the old secret, only the current (new) secret is valid. The old secret can no longer authenticate.

unatasha8 · 2026-02-12T18:44:28Z

docs/hydra/guides/oauth2-clients.mdx

+  id: clientId
+})
+
+// Old secrets are now revoked


Suggested change

// Old secrets are now revoked

// Old secret is now revoked.

unatasha8 · 2026-02-12T18:45:02Z

docs/hydra/guides/oauth2-clients.mdx

+
+echo "New secret: $NEW_SECRET"
+
+# 3. Update your applications with the new secret


Suggested change

# 3. Update your applications with the new secret

# 3. Update your client servcies with the new secret

unatasha8 · 2026-02-12T18:45:39Z

docs/hydra/guides/oauth2-clients.mdx

+  -u "$CLIENT_ID:$NEW_SECRET" \
+  -d "grant_type=client_credentials"
+
+# 5. Once all services are updated, clean up old secrets


Suggested change

# 5. Once all services are updated, clean up old secrets

# 5. Once all client services are updated, remove the old secret

unatasha8 · 2026-02-12T18:46:07Z

docs/hydra/guides/oauth2-clients.mdx

+
+:::tip Zero-downtime credential rotation
+
+Secret rotation enables zero-downtime credential updates. Both the old and new secrets remain valid until you manually clean up


Suggested change

Secret rotation enables zero-downtime credential updates. Both the old and new secrets remain valid until you manually clean up

Secret rotation enables zero-downtime credential updates. Both the old and new secrets remain valid until you manually remove

unatasha8 · 2026-02-12T18:46:31Z

docs/hydra/guides/oauth2-clients.mdx

+:::tip Zero-downtime credential rotation
+
+Secret rotation enables zero-downtime credential updates. Both the old and new secrets remain valid until you manually clean up
+the rotated secrets, allowing you to update all your services without service interruption.


Suggested change

the rotated secrets, allowing you to update all your services without service interruption.

the old secret, allowing you to update all your client services without service interruption.

unatasha8 · 2026-02-12T18:47:04Z

docs/hydra/guides/oauth2-clients.mdx

+
+:::warning Security best practice
+
+Rotated secrets remain valid indefinitely until you explicitly clean them up. Always remove old rotated secrets once your


Suggested change

Rotated secrets remain valid indefinitely until you explicitly clean them up. Always remove old rotated secrets once your

Secrets remain valid indefinitely until you explicitly remove them. Always remove old secrets once your

unatasha8 · 2026-02-12T18:47:38Z

docs/hydra/guides/oauth2-clients.mdx

+:::warning Security best practice
+
+Rotated secrets remain valid indefinitely until you explicitly clean them up. Always remove old rotated secrets once your
+migration is complete to ensure that compromised credentials cannot be used.


Suggested change

migration is complete to ensure that compromised credentials cannot be used.

secret rotation process is complete to ensure that compromised credentials cannot be used.

unatasha8 · 2026-02-12T18:50:14Z

docs/hydra/guides/oauth2-clients.mdx

+
+:::warning Security best practice
+
+Rotated secrets remain valid indefinitely until you explicitly clean them up. Always remove old rotated secrets once your


"secrets remain valid indefinitely" Are you sure? Don't they have a validity date?

Deepak just added this feature: "The SAML connection includes a valid_to attribute, which is an array of expiry dates for the signing certificates associated". This might not directly link to your code as it's for SAML... but wanted to point it out to you.

unatasha8 · 2026-02-12T18:50:59Z

docs/hydra/guides/oauth2-clients.mdx

+3. Update services: Update your applications to use the new secret
+4. Cleanup: Manually remove old rotated secrets once all services are updated
+
+##### Rotate client secret


Suggested change

##### Rotate client secret

##### Rotate OAuth2 client secret

unatasha8 · 2026-02-12T18:52:45Z

docs/hydra/guides/oauth2-clients.mdx

+  -H "Authorization: Bearer ory_pat_..."
+```
+
+The response includes the new `client_secret`. Save this value immediately - it will not be shown again.


Where should this be saved? Is there a secure location it should be saved to?

unatasha8 · 2026-02-12T18:53:30Z

docs/hydra/guides/oauth2-clients.mdx

+</Tabs>
+````
+
+##### Clear rotated secrets


Suggested change

##### Clear rotated secrets

##### Remove old secret

unatasha8

In general, keep to singular for 'secret' if the process is one at a time. Pick one to use client(s), client service(s), service(s), application(s) etc. I tried to change all to client services.

SamuelDev requested review from aeneasr, piotrmsc, unatasha8, vinckr and zepatrik as code owners January 23, 2026 17:17

SamuelDev force-pushed the client-secret-rotation-docs branch from 068aa3d to 5e927b3 Compare January 23, 2026 17:19

SamuelDev mentioned this pull request Jan 23, 2026

feat: Implement client secret rotation ory/hydra#4063

Open

7 tasks

vinckr added the upstream Issue is caused by an upstream dependency. label Jan 23, 2026

alnr added the area/docs This issue affects Ory's documentation. label Feb 10, 2026

alnr assigned unatasha8 Feb 10, 2026

vercel bot deployed to Preview February 11, 2026 22:28 View deployment

vercel bot deployed to Preview February 11, 2026 22:35 View deployment

SamuelDev and others added 6 commits February 11, 2026 20:14

doc changes for client secret rotation

20e4ba2

run format

092745e

fix: update API documentation links for OAuth2 client secrets

cf5d2be

fix: revert auto-generated api.json

018837b

chore: format

8c18152

chore: format

29299a0

vinckr force-pushed the client-secret-rotation-docs branch from 19afb45 to 29299a0 Compare February 11, 2026 23:14

vinckr reviewed Feb 11, 2026

View reviewed changes

vercel bot deployed to Preview February 11, 2026 23:20 View deployment

unatasha8 reviewed Feb 12, 2026

View reviewed changes

unatasha8 requested changes Feb 12, 2026

View reviewed changes

	remains valid until you explicitly clean it up, allowing you to update all services using the client credentials without service
	remains valid until you remove it, allowing you to update all your services without service


		##### How secret rotation works

		1. Rotate the secret: Generate a new secret for the client

	1. Rotate the secret: Generate a new secret for the client
	1. Generate a new secret for the client service

	3. Update services: Update your applications to use the new secret
	3. Update your client services to use the new secret

	4. Cleanup: Manually remove old rotated secrets once all services are updated
	4. After you test the client services can authenticate with the new secret, manually remove the old secret.


		##### Clear rotated secrets

		Once all services have been updated to use the new secret, you can remove the old rotated secrets to revoke access using the old

	Once all services have been updated to use the new secret, you can remove the old rotated secrets to revoke access using the old
	Once all services are updated to use the new secret, remove the old secret to revoke access using the old

	After cleanup, only the current secret will be valid. Old secrets will no longer authenticate.
	After removing the old secret, only the current (new) secret is valid. The old secret can no longer authenticate.


		echo "New secret: $NEW_SECRET"

		# 3. Update your applications with the new secret

	# 3. Update your applications with the new secret
	# 3. Update your client servcies with the new secret

	# 5. Once all services are updated, clean up old secrets
	# 5. Once all client services are updated, remove the old secret


		:::tip Zero-downtime credential rotation

		Secret rotation enables zero-downtime credential updates. Both the old and new secrets remain valid until you manually clean up

	the rotated secrets, allowing you to update all your services without service interruption.
	the old secret, allowing you to update all your client services without service interruption.


		:::warning Security best practice

		Rotated secrets remain valid indefinitely until you explicitly clean them up. Always remove old rotated secrets once your

	Rotated secrets remain valid indefinitely until you explicitly clean them up. Always remove old rotated secrets once your
	Secrets remain valid indefinitely until you explicitly remove them. Always remove old secrets once your

	migration is complete to ensure that compromised credentials cannot be used.
	secret rotation process is complete to ensure that compromised credentials cannot be used.

feat: Docs for client secret rotation #2424

Are you sure you want to change the base?

feat: Docs for client secret rotation #2424

Conversation

SamuelDev commented Jan 23, 2026

Related Issue or Design Document

Checklist

Further comments

Uh oh!

SamuelDev commented Jan 23, 2026

Uh oh!

alnr commented Feb 11, 2026

Uh oh!

vinckr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

unatasha8 Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

unatasha8 Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

unatasha8 Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

unatasha8 Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

unatasha8 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

unatasha8 Feb 12, 2026 •

edited

Loading

unatasha8 Feb 12, 2026 •

edited

Loading

unatasha8 Feb 12, 2026 •

edited

Loading

unatasha8 Feb 12, 2026 •

edited

Loading