# Adding an Admin Page

> Add a page to /admin safely: authorize with requireAdmin in the loader and every action, copy in a server-only namespace, writes as POST actions.

*Canonical: https://makerkit.dev/docs/void-cloudflare/admin/adding-admin-pages*

---

An admin page is a Void page under `apps/web/pages/admin/`. The rules are the same ones the kit's pages follow.

Overview pages use `AdminPageHeader` from `@kit/admin/ui`: pass the translated `title`, `description` and heading `testId`. It groups the title and description, with a sidebar toggle on mobile only. Keep search and filter controls in a wrapping row inside `PageBody`; detail pages use `<PageHeader displayTrigger="mobile">` for their back link and keep their record actions.

## 1. Pick or Add a Statement

A statement is `resource:action` (`user:ban`). Use one the roles already hold, or add yours in `packages/rbac/src/admin-rbac.config.ts` and declare it so `requireAdmin` accepts it by name:

```ts
// apps/web/types/admin.d.ts
declare module '@kit/admin' {
  interface CustomAdminStatements {
    'subscriptions:refund': true;
  }
}
```

A statement the config doesn't define is granted to nobody. See [RBAC permissions](./rbac-permissions).

## 2. Authorize in the Loader

```ts
// apps/web/pages/admin/subscriptions.server.ts
import { defineHandler, type InferProps } from 'void';

import { requireAdmin } from '#/lib/admin.server.ts';

export type Props = InferProps<typeof loader>;

export const loader = defineHandler(async (c) => {
  requireAdmin({ c, statement: 'subscriptions:list' });

  return { rows: await listSubscriptions() };
});
```

`requireAdmin` throws the app's **404** (never 403) for anyone not allowed, so the page doesn't reveal it exists. The middleware gate only guides navigation: **every** loader and **every** action calls `requireAdmin` itself, with the statement that action needs.

## 3. Writes Are POST Actions

```ts
export const actions = {
  refund: defineHandler.withValidator({ body })(async (c, { body }) => {
    const { admin } = requireAdmin({ c, statement: 'subscriptions:refund' });
    // …
  }),
};
```

A `GET` (and link prefetch) never changes anything. For a destructive action add a step-up code, as ban, role change and impersonation do. After the write has committed, record an audit event with `recordAudit` and an action of your own ([Add Your Own Actions](../audit/adding-actions)): ids only, never emails, tokens or payloads. The `kit.admin.*` actions are the kit's; you can't declare one.

## 4. Copy in a Server-Only Namespace

Admin copy never goes to the browser bundle. Put yours in a `<namespace>.server.json` under `apps/web/messages/<locale>/` (for example `adminSubscriptions.server.json`), read it in the loader with `getServerTranslator({ c, namespace })` and pass the text as props. The kit's own pages use `admin.server.json` the same way.

## 5. Check It

- A test that a signed-out request, a normal user and an organization admin get 404 on the page and on each action.
- An entry in `apps/e2e/tests/admin/` for what an admin does there.

The sidebar lists the kit's own pages (`packages/admin/src/navigation.ts`): reach yours by URL, or link to it from your own admin pages.
