From 4fa4b544805f95ab5dbbbbf14f056b56875ec567 Mon Sep 17 00:00:00 2001
From: Henning Perl <henning.perl@ory.sh>
Date: Fri, 16 Feb 2024 16:50:48 +0100
Subject: [PATCH] feat: document mirror_top_level_claims (#1652)

---
 docs/oauth2-oidc/jwt-access-token.mdx | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/oauth2-oidc/jwt-access-token.mdx b/docs/oauth2-oidc/jwt-access-token.mdx
index 6b9ca3a56..925ebd909 100644
--- a/docs/oauth2-oidc/jwt-access-token.mdx
+++ b/docs/oauth2-oidc/jwt-access-token.mdx
@@ -169,3 +169,27 @@ Which results in an access token with the following structure:
   // ...
 }
 ```
+
+### Disable mirroring the claims under `ext`
+
+By default, all custom claims will be mirrored in the `ext` claim (as is the case with the claim `some_custom_claim` in the
+example above).
+
+Set `oauth2.mirror_top_level_claims` to `false` to disable mirroring the claims in the nested `ext` claim:
+
+```shell
+ory patch oauth2-config {project.id} \
+  --replace "/oauth2/mirror_top_level_claims=false"
+```
+
+This results in an access token with the following structure:
+
+```json
+{
+  "sub": "...",
+  // ...
+  "some_custom_claim": "some_custom_value"
+  // no "ext" claim
+  // ...
+}
+```