feat: Docs for client secret rotation by SamuelDev · Pull Request #2424 · ory/docs

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

+## 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

+
+##### 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

+##### 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

+
+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

+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

+
+##### 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

+##### 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

+  -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

+  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

+
+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

+  -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

+
+:::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

+:::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

+
+:::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

+:::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

+
+:::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

+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

+  -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

+</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.

Apply the terminology suggestions from the review: singular "secret", and "client service" used consistently. Also fix the rotation endpoint path. All four curl examples used /admin/clients/{id}/secret/rotate, but the implemented route is /admin/clients/{id}/secrets/rotate, so every example returned 404. Answer the two open review questions in the text: say where to store the new secret, and confirm that secrets do not expire on their own. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

alnr · 2026-07-09T13:50:01Z

Pushed 056df20 to address @unatasha8's review. Summary of what changed, including three places where I did not apply a suggestion literally — flagging those so you can push back.

Applied

Singular "secret" throughout, and "client service(s)" used consistently, per the general note.
"Clear rotated secrets" → "Remove old secret"; "cleanup" wording removed everywhere.
The two admonitions and the workflow example comments now use the agreed terminology.

Bug found while editing

All four curl examples used /admin/clients/{id}/secret/rotate (singular). The implemented route is /admin/clients/{id}/secrets/rotate (plural) — see client/handler.go and the OpenAPI spec in ory-corp/cloud#10632. Every example on this page would have returned 404. Fixed.

Answers to the open questions

"Where should this be saved?" (line 160) — the text now says Ory shows the value only once and to store it in the secret store the client services read from (a secrets manager or an encrypted environment configuration).
"'Secrets remain valid indefinitely' — are you sure? Don't they have a validity date?" (line 260) — confirmed correct. Rotated secrets are stored in the rotated_secrets column with no expiry field and no TTL; they stay valid until explicitly deleted. That is exactly why the warning admonition exists. This is unlike the SAML valid_to attribute you mentioned, which is a different feature.

Deviations from the literal suggestions

Ordering of "How secret rotation works" — the suggestion moves "Both old and new secrets authenticate" to step 3, after "Update your client services". That would imply the dual-validity window starts once you update your services. It actually starts the moment you rotate. I kept the dual-validity statement attached to step 1 and added your "test before removing" step as step 3:
1. Generate a new secret for the client service. Both the old and the new secret authenticate from this point on.
2. Update your client services to use the new secret.
3. Test that the client services can authenticate with the new secret.
4. Manually remove the old secret. Only the new secret authenticates from this point on.
##### Rotate OAuth2 client secret — left as ##### Rotate client secret. The ## heading directly above is already "Rotate OAuth2 client secret", so the suggestion would create two identical headings and an ambiguous #rotate-oauth2-client-secret-1 anchor.
"servcies" in the step-3 suggestion is a typo; used "services".

Happy to take any of these the other way — say the word.

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

alnr requested a review from unatasha8 July 9, 2026 13:50

	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.

Uh oh!

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!

alnr commented Jul 9, 2026

Applied

Bug found while editing

Answers to the open questions

Deviations from the literal suggestions

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