docs: Document isRestricted and restrictedReason JWT claims#1136
docs: Document isRestricted and restrictedReason JWT claims#1136madster456 merged 7 commits intodevfrom
Conversation
![promptless[bot]](https://avatars.githubusercontent.com/in/979718?s=60&v=4){kind=small}
| - **`email_verified`**: Whether the user's email has been verified | ||
| - **`selected_team_id`**: The currently selected team ID (nullable) | ||
| - **`is_anonymous`**: Whether this is an anonymous user session | ||
| - **`is_restricted`**: Whether the user is restricted (e.g., unverified email or anonymous) |
There was a problem hiding this comment.
Citation: Added is_restricted and restricted_reason JWT claims based on PR #1069 "Onboarding app & restricted users". See packages/stack-shared/src/schema-fields.ts for the schema definition of these fields and apps/backend/src/lib/tokens.tsx for how they're added to tokens.
View source
| - `restricted_reason` is `{ "type": "anonymous" }` | ||
|
|
||
| Restricted user tokens (e.g., users who haven't verified their email when verification is required) have: | ||
|
|
There was a problem hiding this comment.
Citation: Documented restricted user token structure including the :restricted audience suffix. See apps/backend/src/lib/tokens.tsx for audience derivation logic and apps/backend/src/app/api/latest/users/crud.tsx for the computeRestrictedStatus() function that determines when users are restricted.
View source
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
|
|
Important Review skippedBot user detected. To trigger a single review, invoke the You can disable this status message by setting the
Comment |
Greptile OverviewGreptile SummaryThis PR documents the Key changes:
Verification: Confidence Score: 5/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant Client
participant StackAuth as Stack Auth API
participant App as Application Backend
Note over Client,App: Regular User Authentication Flow
Client->>StackAuth: Sign in request
StackAuth->>StackAuth: Check restriction status
alt User has verified email
StackAuth->>Client: Access Token (not restricted)<br/>Audience: project_id
else User email not verified
StackAuth->>Client: Restricted Token<br/>Audience: project_id:restricted
end
Note over Client,App: Anonymous User Flow
Client->>StackAuth: Create anonymous session
StackAuth->>Client: Anonymous Token<br/>Audience: project_id:anon
Note over Client,App: Manual JWT Verification
App->>StackAuth: GET JWKS endpoint with include_restricted
StackAuth->>App: Return JWKS including restricted keys
Client->>App: API request with JWT
App->>App: Verify JWT signature using JWKS<br/>Check audience matches token type
App->>Client: Response based on user restrictions
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
🔧 I noticed that some CI checks failed for this PR. I'm investigating the failures and will work on fixing them. |
1 similar comment
|
🔧 I noticed that some CI checks failed for this PR. I'm investigating the failures and will work on fixing them. |
|
@Promptless move the code examples into docs/code-examples/concepts/jwt.ts instead of just docs/code-examples/concepts.ts, this makes it more clear what the code examples are tied to within concepts. |
|
I've added new changes to address this PR comment in commit b9eb62d |
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
|
🔧 I noticed that some CI checks failed for this PR. I'm investigating the failures and will work on fixing them. |
|
I've added new changes to address this CI failure in commit 6c2dc5a |
|
🔧 I noticed that some CI checks failed for this PR. I'm investigating the failures and will work on fixing them. |
|
I've added new changes to address this CI failure in commit 7f02cac |
|
|
||
| Restricted user tokens (e.g., users who haven't verified their email when verification is required) have: | ||
|
|
||
| - `iss` remains unchanged (same as regular users) |
There was a problem hiding this comment.
Citation: Corrected the iss claim documentation for restricted users based on the getIssuer() function in apps/backend/src/lib/tokens.tsx. The function shows restricted users get a -restricted-users suffix in their issuer URL, not the same issuer as regular users.
View source
|
I've added new changes to address this GitHub Commit in commit e433f29 |
| - **`selected_team_id`**: The currently selected team ID (nullable) | ||
| - **`is_anonymous`**: Whether this is an anonymous user session | ||
| - **`is_restricted`**: Whether the user is restricted (e.g., unverified email or anonymous) | ||
| - **`restricted_reason`**: Why the user is restricted (nullable). The `type` field is either `anonymous` or `email_not_verified` |
There was a problem hiding this comment.
Citation: Commit "Fix restricted user schema" (e5a3546) consolidates the RestrictedReason type across the codebase to consistently include all three types: anonymous, email_not_verified, and restricted_by_administrator. See changes in packages/stack-shared/src/schema-fields.ts where restrictedReasonSchema was created, and sdks/spec/src/types/users/base-user.spec.md for the updated SDK spec.
View source
2 participants
Open this suggestion in Promptless to view citations and reasoning process
Documents the new
is_restrictedandrestricted_reasonJWT claims introduced for the onboarding/restricted users feature. Updates the JWT documentation to explain these fields in the claims section, adds them to the example payload, documents the restricted user token structure, and adds theinclude_restrictedJWKS parameter for manual token verification.Trigger Events
stack-auth/stack-auth commit (dev): de0f937 [CHANGELOG] - 2026.01.21
Promptless Research (1 webpage, 1 GitHub PR)
Agent Response
Help us improve Promptless — If this suggestion missed the mark, please share quick feedback.
If you want Promptless to make further changes on this PR, feel free to leave a comment tagging Promptless (It won't show up in the user drop down but Promptless will get it!)