Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hexclave.com/llms.txt

Use this file to discover all available pages before exploring further.

Restricted users are signed-in users whose account exists, but has not been granted normal application access yet. Stack marks these users with user.isRestricted === true and provides a user.restrictedReason explaining why. By default, Stack Auth treats restricted users like unauthenticated users in most SDK calls. This prevents accounts that still need verification, review, or conversion from accidentally getting access to protected product flows.

​
When users are restricted

Users can be restricted for a few reasons:
  • Email not verified: the project requires email verification before full access.
  • Anonymous user: anonymous users can interact with the app, but are always restricted until converted.
  • Restricted by administrator: the user was restricted manually or by a sign-up rule.
You can inspect the reason from the SDK:
my-app.ts
import { stackServerApp } from "../src/stack/server";

const user = await stackServerApp.getUser({ includeRestricted: true });

if (user?.isRestricted) {
  console.log(user.restrictedReason?.type);
}
The current restrictedReason.type values are:
TypeMeaning
email_not_verifiedThe user still needs to verify their email address.
anonymousThe user is an anonymous user.
restricted_by_administratorThe user was restricted manually or by a sign-up rule.

​
Loading restricted users

Most calls exclude restricted users unless you explicitly opt in. Use includeRestricted: true when you are building onboarding, email verification, account review, or anonymous-user conversion flows.
my-app.ts
import { stackServerApp } from "../src/stack/server";

const user = await stackServerApp.getUser({ includeRestricted: true });

if (user?.isRestricted) {
  console.log("Needs onboarding:", user.restrictedReason?.type);
}
Anonymous users are restricted by definition. Passing { or: "anonymous" } automatically includes restricted users, and cannot be combined with { includeRestricted: false }.

​
Handling restricted users

Treat restricted users as a separate state from both “signed out” and “fully signed in”. A good default is to show a page that tells the user what they need to do next.
restricted-user-message.tsx
function RestrictedUserMessage({ reason }: { reason: string | undefined }) {
  if (reason === "email_not_verified") {
    return <div>Please verify your email address to continue.</div>;
  }

  if (reason === "anonymous") {
    return <a href="/handler/sign-up">Create an account to save your progress.</a>;
  }

  return <div>Your account is waiting for review.</div>;
}
For API routes or backend actions, keep using the default behavior unless the endpoint is specifically meant to serve restricted users. This helps prevent partially onboarded accounts from reaching product APIs.

​
Restricted users in JWTs

Restricted users receive tokens with is_restricted and restricted_reason claims. If your backend verifies Stack Auth JWTs directly, make sure you reject restricted users unless the endpoint intentionally supports them. When fetching Stack Auth’s JWKS, restricted-user signing keys are excluded by default. Include them only for services that intentionally accept restricted users:
jwks-url.txt
/.well-known/jwks.json?include_restricted=true
If you also accept anonymous users, use include_anonymous=true; anonymous keys imply restricted-user keys.

​
Admin and sign-up review

Sign-up rules can restrict a user instead of rejecting the sign-up outright. This is useful when you want the account to exist, but need manual review before granting access. For more details on creating rules that restrict users, see Sign-up Rules.