Technology handbook
Clerk user management
Hosted authentication, prebuilt components, organizations, webhooks and route protection.
- Topics
- 28
- Sections
- 4
Hooks
useUser
Read the signed-in user and their metadata reactively, with a loaded flag.
- It returns the full user object, which is more than a page needing only an id should load.
- The loaded flag is what separates signed out from not yet known.
- Metadata read here is the client-visible half, never the private half.
useAuth
Read the session and user ids, and fetch a token, without pulling the whole user object.
- It gives the user and session ids without deserialising the whole user.
- Fetching a token here is how a call to your own API is authorized.
- It is the cheaper hook for a component that only guards on identity.
useClerk
Reach the Clerk instance for imperative calls such as opening a sign-in modal.
- It exposes the instance for imperative calls such as opening a modal.
- Nothing it returns re-renders the component, so state must come from elsewhere.
- It is for event handlers, not for deciding what to render.
useSession
Read the active session, including its status and last-active time.
- The active session carries its status and last-active time, not just the user.
- Session status is what distinguishes expired from signed out.
- It reflects one session even when the browser holds several.
useSessionList
List every session in the browser to build an account switcher.
- Every session in the browser is listed, which is what an account switcher renders.
- Switching the active session changes what every other hook reports.
- The list is per browser, so it says nothing about sessions on other devices.
useSignIn and useSignUp
Drive a custom authentication flow step by step instead of the prebuilt components.
- They drive the flow step by step when the prebuilt components do not fit.
- Each step returns the next required factor rather than a finished session.
- The flow must handle every branch, including verification and multi-factor.
useOrganization
Read the active organization, its membership and the current user's role in it.
- It reports the active organization, its membership and the caller's role in it.
- Role read here is what a tenant-scoped interface renders against.
- It returns null when no organization is active, which is a real state to handle.
useOrganizationList
List the organizations a user belongs to and switch the active one.
- It lists the organizations a user belongs to and switches the active one.
- Switching re-issues the token, so server checks see the new tenant.
- The list is paginated, so a user in many organizations is not fully loaded at once.
useReverification
Require a fresh credential check before a sensitive action completes.
- A sensitive action can demand a fresh credential check before it completes.
- It proves the person at the keyboard now, not whoever signed in hours ago.
- The challenge is per action, so passing it once does not unlock the rest.
Loaded flags before rendering
Every hook reports whether Clerk has loaded, and rendering before it flashes the wrong state.
- Every hook reports whether Clerk has finished loading.
- Rendering before it resolves flashes signed-out content at a signed-in user.
- The flag is the guard; the absence of a user is not the same as no user.
Setup & components
Provider setup
Wrap the application so client components can read auth state.
- Wrapping the tree is what lets client components read auth state at all.
- The provider must sit above every consumer, which in practice means the root layout.
- Keys read here are publishable; the secret key must never reach this boundary.
Prebuilt components
Use SignIn, SignUp and UserButton before building custom flows.
- They carry the flows, validation and error states already written.
- Replacing them with custom flows means owning every branch they handle.
- They render Clerk's markup, so page styling has to work through the appearance API.
Appearance customization
Restyle the components to match the product.
- Styling goes through the appearance API rather than by overriding the markup.
- Variables restyle every component at once; element overrides target one.
- Targeting internal class names breaks on a library upgrade.
Custom flows
Drive sign-in with the hooks when the prebuilt UI does not fit.
- The hooks drive the steps when the prebuilt interface does not fit the product.
- Every factor and error the components handled becomes yours to handle.
- Sign-in and sign-up are separate flows even when the screen looks like one.
Environment keys
Separate publishable and secret keys and keep the secret server-side.
- The publishable key is safe in the browser; the secret key is not.
- A secret key reaching the client bundle is a full compromise, not a leak.
- Each instance has its own pair, so promoting a build means swapping both.
Local development
Run against a development instance with its own users.
- A development instance keeps test users out of the production directory.
- Its keys and its user list are separate, so data never crosses over.
- Development instances relax some checks, which hides issues until production.
Sessions & protection
Middleware
Protect route groups and declare which routes stay public.
- Protection runs before the route renders, so nothing unauthorized is produced.
- Public routes must be declared, because the default is to protect.
- A matcher that includes static assets charges every asset an auth check.
Server-side auth
Read the user id on the server before querying application data.
- Reading the user id on the server is what scopes the query that follows.
- Trusting a client-supplied id instead is how one user reads another's rows.
- It reads the request, so it makes the route dynamic.
Session tokens
Understand the short-lived JWT and its automatic refresh.
- The token is short-lived and refreshed by the client automatically.
- Short lifetime is what limits the damage of one being captured.
- Anything cached from it is stale as soon as the token rotates.
Custom claims
Add metadata to the token so authorization needs no extra lookup.
- Claims in the token let the server authorize without a second lookup.
- A claim is only as fresh as the token carrying it.
- An oversized claim set pushes the token past what a cookie will hold.
Multi-session handling
Support a user signed into several accounts at once.
- One browser can hold several signed-in accounts at once.
- Every server check must read the active session rather than assume one.
- Switching accounts changes the id your queries must be scoped by.
Sign-out and revocation
End a session everywhere rather than only in one tab.
- Signing out of one tab is not the same as ending the session everywhere.
- Revoking server-side is what stops an already-issued token being used.
- Until the token expires, a revoked session may still pass a naive check.
Organizations & data
Organizations
Model teams with memberships, roles and an active organization.
- Teams are modelled as memberships with roles and one active organization.
- The active organization scopes both the interface and the server query.
- A user with no organization is a state the interface has to render.
Invitations
Invite members and handle acceptance into the right organization.
- An invitation resolves to a membership in a specific organization on acceptance.
- Accepting with a different email than invited is the case that must be refused.
- Pending invitations expire, or they become a standing way in.
Role-based permissions
Authorize actions by organization role on the server.
- Authorization is by organization role, checked on the server.
- The same user holds different roles in different organizations.
- A client-side role check hides a control; it does not protect the action.
User and public metadata
Choose what the client may read and what stays private.
- Public metadata is readable by the client; private metadata is not.
- Putting a role in public metadata lets the client read it and the server still verify it.
- Anything secret in public metadata is published, not merely exposed.
Webhooks
Mirror user and organization events into your own database.
- Events mirror user and organization changes into your own database.
- The local copy is a mirror, so Clerk stays the source of truth for identity.
- A missed event leaves the mirror wrong until the next one arrives.
Signature verification and idempotency
Verify every webhook and make handling safe to repeat.
- An unverified webhook is an open endpoint anyone may post to.
- Delivery is at least once, so the same event will arrive twice.
- Keying on the event id is what makes repeated handling harmless.
Sources
- Clerk user management official documentation