# Users, Sessions and Permissions

> Read the authenticated user on the server or in React, protect handlers, and authorize personal, organization and admin data.

*Canonical: https://makerkit.dev/docs/void-cloudflare/development-guide/users-and-permissions*

---

Authentication in this kit is self-managed Better Auth. The session middleware resolves it for the request; your code uses the kit's session helpers. Do not import `void/auth` or the `auth` client from `void/client`.

## Require a User on the Server

Use `requireSession({ c })` in every loader, action, or API handler that needs an authenticated user:

```ts
import { defineHandler } from 'void';
import { requireSession } from '#/lib/session.server.ts';

export const loader = defineHandler((c) => {
  const { user } = requireSession({ c });
  return { name: user.name };
});
```

It returns `{ user, session }`. Without a session it redirects page requests to sign-in, preserving a safe return path, and answers API requests with 401. An authentication backend failure is not treated as a valid signed-out request to protected data.

Only return the fields the browser needs. The full session, its token, and privileged auth records stay on the server.

## Allow Signed-out Visitors

Use `getSession({ c })` on a public page where signing in is optional:

```ts
import { defineHandler } from 'void';
import { getSession } from '#/lib/session.server.ts';

export const loader = defineHandler((c) => {
  const session = getSession({ c });
  return { signedIn: Boolean(session) };
});
```

The result is `{ user, session }` or `null`. This does not grant a public page permission to return private records. Any personalized response must remain private rather than entering a public edge cache.

## Read the User in React

```tsx
import { useShared } from '@void/react';

export function CurrentUserName() {
  const { user } = useShared();
  return user ? <span>{user.name}</span> : null;
}
```

The shared user contains `id`, `name`, `email`, `image`, and `emailVerified`. It is useful for rendering account menus and controls. A browser-side user check never substitutes for server authorization.

For browser auth flows, use `authClient` from `@kit/better-auth/client`. The existing sign-in and account components handle rate limits, errors, and navigation. Server-side sign-in calls bypass the HTTP rate limiter, so keep user sign-in flows on the browser client.

## Personal Data

Derive the owner id from `requireSession`, then pass it to a scoped service:

```ts
const { user } = requireSession({ c });
const profile = await findAccountSummary({ userId: user.id });
```

`findAccountSummary` is defined in [Fetching Data](./data-fetching). Never accept the acting user's id from a hidden form field. For a resource lookup or update, filter by both its resource id and its session-derived owner id; possession of a UUID is not authorization.

## Organization Data

Read the active organization through the kit's membership helpers:

```ts
import { requireActiveOrganization } from '#/lib/organizations.server.ts';

const organization = requireActiveOrganization({ c });
```

This requires a session and an active membership; it answers 404 in personal-account context. Scope every organization query to `organization.id`. The kit does not apply row-level security for you.

An organization mutation also checks permission and stale-tab context:

```ts
import { requireOrganizationAction } from '#/lib/organizations.server.ts';

const organization = requireOrganizationAction({
  c,
  organizationId: body.organizationId,
  permission: { resource: 'project', action: 'create' },
});
```

This is a pattern for a custom `project` resource, not a built-in permission. Register that resource and assign it to roles in `packages/rbac/src/rbac.config.ts` before using it. `body` must come from your action's validator. The form sends the organization it was rendered for; the helper compares it with the current membership and returns 409 if the user switched organizations in another tab. Use the helper's returned organization id for the write, never the unchecked form value.

For the full implementation, see [Scoping Data](../organizations/scoping-data) and [Roles and Permissions](../members-management/roles-permissions). Existing organization services, such as `organizationsFor(c).organizations.rename(...)`, already apply their business authorization rules.

## Admin and Sensitive Account Changes

Admin pages and handlers call `requireAdmin({ c, statement })` with an explicit admin permission. Admin refusals return 404; the UI alone cannot grant admin access. See [Super Admin](../admin/overview).

Email changes, password changes, and linked sign-in methods require a fresh, non-impersonation session. Reuse the existing account services rather than bypassing these rules with a direct table update. See [Sessions and Guards](../authentication/sessions-and-guards) for the complete session lifecycle.

---

**Next:** [Build an API Route →](./api-routes)
