Permissions

Staff permissions decide what each AdminCP administrator or moderator may do. A plugin declares its own, the AdminCP lets you grant them, and routes check them on the server. In this lesson you declare Create notes for site-notes and add POST /api/site-notes/admin/notes, which only administrators holding it can call.

Before you beginCopy Anchor Link

• The site_notes table from Database, with pnpm dev running.
• A second account to restrict. Register one at /register in a private window; only the first account became the administrator.

import { defineStaffPermissions } from "@vitnode/core/lib/staff-permissions";

import { manifest } from "@/manifest.gen";

export const staffPermissions = defineStaffPermissions(manifest, {
  admin: { notes: ["can_create"] },
});

import { staffPermissions } from "@/staff-permissions"; 

export const siteNotesApiPlugin = () =>
  buildApiPlugin({
    manifest,
    modules: [helloModule, notesModule],
    permissionStaff: staffPermissions, 
  });

export const staffPermissions = defineStaffPermissions(manifest, {
  admin: { notes: ["can_create"] },
  moderator: { notes: ["can_delete"] }, 
});

{
  "site-notes": {
    "title": "Site Notes"
  },
  "site-notes:notes": "Notes",
  "site-notes:notes:can_create": "Create notes"
}

import { z } from "@hono/zod-openapi";

import { buildRoute } from "@/api/builders";
import { site_notes } from "@/database/notes";
import { staffPermissions } from "@/staff-permissions";

import { zodNote } from "../../../notes/notes.schema";

export const createNoteRoute = buildRoute({
  adminStaffPermission: staffPermissions.admin.notes.canCreate,
  route: {
    method: "post",
    path: "/",
    request: {
      body: {
        content: {
          "application/json": {
            schema: z.object({
              title: z.string().trim().min(3).max(200),
              body: z.string().trim().min(1).max(2000)
            })
          }
        }
      }
    },
    responses: {
      201: {
        content: { "application/json": { schema: zodNote } },
        description: "The created note."
      }
    }
  },
  handler: async (c) => {
    const values = c.req.valid("json");
    const [note] = await c
      .get("db")
      .insert(site_notes)
      .values(values)
      .returning({ id: site_notes.id, title: site_notes.title, body: site_notes.body });

    return c.json(note, 201);
  }
});

import { buildModule } from "@/api/builders";

import { createNoteRoute } from "./routes/create.route";

export const adminNotesModule = buildModule({
  name: "notes",
  routes: [createNoteRoute]
});

import { buildModule } from "@/api/builders";

import { adminNotesModule } from "./notes/notes.module";

export const adminModule = buildModule({
  name: "admin",
  routes: [],
  modules: [adminNotesModule]
});

import { adminModule } from "./api/modules/admin/admin.module"; 

    modules: [helloModule, notesModule], 
    modules: [helloModule, notesModule, adminModule], 

Check the resultCopy Anchor Link

Add a temporary button that calls the route with fetcher. Create src/pages/check-create-note.tsx:

import { Button } from "@vitnode/core/components/ui/button";
import { fetcher } from "@vitnode/core/tanstack/fetcher";
import { useState } from "react";

import { manifest } from "@/manifest.gen";

export const CheckCreateNote = () => {
  const [status, setStatus] = useState<number>();
  const [isPending, setIsPending] = useState(false);

  const onClick = async () => {
    setIsPending(true);
    try {
      const response = await fetcher({
        plugin: manifest.id,
        method: "post",
        module: "admin/notes",
        path: "/",
        args: {
          body: {
            title: "Parking lot repaint",
            body: "The lot is closed on Saturday morning."
          }
        }
      });
      setStatus(response.status);
    } finally {
      setIsPending(false);
    }
  };

  return (
    <div className="flex items-center gap-3">
      <Button isLoading={isPending} onClick={onClick}>
        Create a test note
      </Button>
      {status ? <output>{status}</output> : null}
    </div>
  );
};

Render <CheckCreateNote /> above the list in src/pages/notes-page.tsx. The browser sends the AdminCP session cookie from every page, so sign in to the AdminCP as each account, open /site-notes/notes in that browser and press the button:

Now edit the restricted account in Staff → Administrators, choose Site Notes in the plugin list, tick Create notes under Notes and save. The same button pressed as that account shows 201. Remove CheckCreateNote when you are done.

The check happens on the server. Hiding a button or a sidebar link only tidies the UI, and the AdminCP page lesson does both on top of this guard.

Depend on another permissionCopy Anchor Link

When one permission only makes sense with another, declare the dependency. The editor locks the dependent permission until you tick its prerequisite:

export const staffPermissions = defineStaffPermissions(manifest, {
  admin: {
    notes: [
      "can_view",
      { permission: "can_create", dependsOn: ["can_view"] },
      { permission: "can_delete", dependsOn: ["can_view"] },
    ],
  },
});

Each permission you add needs its own label and its own adminStaffPermission on the routes it protects. Permission references covers the naming rule, other plugins' permissions and Content Engine permissions.

Check a permission in codeCopy Anchor Link

adminStaffPermission and moderatorStaffPermission cover a whole route. They decide who may call it, not which notes that person may touch: a guard is not resource authorization. For a decision inside a handler, such as letting staff edit any note but members only their own, call checkStaffPermission(c, { type, plugin, module, permission }) from @vitnode/core/api/lib/check-staff-permission; it resolves to true or false. staffPermissionArgs(ref) from @vitnode/core/lib/staff-permissions turns a reference into those plugin, module and permission fields.

In AdminCP components, useAdminPermission({ plugin, module, permission }) from @vitnode/core/tanstack/admin answers the same question for the signed-in administrator, for showing or hiding controls.

Moderator permissionsCopy Anchor Link

A moderator acts on the site with their normal member session, so moderator routes live in a public module, not under admin. These examples declare two moderator permissions:

export const staffPermissions = defineStaffPermissions(manifest, {
  admin: { notes: ["can_create"] },
  moderator: { notes: ["can_delete", "can_view_details"] },
});

{
  "site-notes:notes:can_delete": "Delete notes",
  "site-notes:notes:can_view_details": "See note details"
}

Grant them in Staff → Moderators (/admin/core/staff/moderators). Choose Add Moderator, pick the member and save. The moderator's edit page opens; keep Restricted, choose Site Notes and tick the permissions.

Pick the check by what a missing permission should do:

All three check the signed-in member, and a signed-out visitor never passes.

Guard a whole routeCopy Anchor Link

moderatorStaffPermission works like adminStaffPermission, but checks the member's site session and takes a reference from staffPermissions.moderator. An admin reference, even one with the same module and name, is a compile error there. Anyone who is not a moderator with Delete notes gets 403 before the handler runs:

import { z } from "@hono/zod-openapi";
import { eq } from "drizzle-orm";

import { buildRoute } from "@/api/builders";
import { site_notes } from "@/database/notes";
import { staffPermissions } from "@/staff-permissions";

export const deleteNoteRoute = buildRoute({
  moderatorStaffPermission: staffPermissions.moderator.notes.canDelete,
  route: {
    method: "delete",
    path: "/{id}",
    request: {
      params: z.object({ id: z.coerce.number().int().positive() })
    },
    responses: {
      204: { description: "The note is gone." },
      403: { description: "The member is not a moderator with Delete notes." },
      404: { description: "No note has this id." }
    }
  },
  handler: async (c) => {
    const { id } = c.req.valid("param");
    const [deleted] = await c
      .get("db")
      .delete(site_notes)
      .where(eq(site_notes.id, id))
      .returning({ id: site_notes.id });
    if (!deleted) return c.body(null, 404);

    return c.body(null, 204);
  }
});

Add it to the routes of notesModule. Call it with fetcher, for example from a Delete button on the notes page:

const response = await fetcher({
  plugin: manifest.id,
  method: "delete",
  module: "notes",
  path: "/{id}",
  args: { params: { id: note.id } }
});

Signed in as the moderator, response.status is 204; for any other member it is 403.

Show moderators moreCopy Anchor Link

The public note route answers everyone, and adds when the note was written for moderators with See note details. checkStaffPermission resolves to true or false instead of refusing:

import { z } from "@hono/zod-openapi";
import { checkStaffPermission } from "@vitnode/core/api/lib/check-staff-permission";
import { staffPermissionArgs } from "@vitnode/core/lib/staff-permissions";
import { eq } from "drizzle-orm";

import { buildRoute } from "@/api/builders";
import { site_notes } from "@/database/notes";
import { staffPermissions } from "@/staff-permissions";

import { zodNote } from "../notes.schema";

export const showNoteRoute = buildRoute({
  route: {
    method: "get",
    path: "/{id}",
    request: {
      params: z.object({ id: z.coerce.number().int().positive() })
    },
    responses: {
      200: {
        content: {
          "application/json": {
            schema: zodNote.extend({ createdAt: z.string().optional() })
          }
        },
        description: "The note. Moderators with See note details also get createdAt."
      },
      404: { description: "No note has this id." }
    }
  },
  handler: async (c) => {
    const { id } = c.req.valid("param");
    const [note] = await c.get("db").select().from(site_notes).where(eq(site_notes.id, id));
    if (!note) return c.body(null, 404);

    const canViewDetails = await checkStaffPermission(c, {
      type: "moderator",
      ...staffPermissionArgs(staffPermissions.moderator.notes.canViewDetails)
    });

    return c.json(
      {
        id: note.id,
        title: note.title,
        body: note.body,
        ...(canViewDetails ? { createdAt: note.createdAt.toISOString() } : {})
      },
      200
    );
  }
});

• The extra field is optional in the schema, so the fetcher types it as string | undefined and the page shows it only when it is there.
• staffPermissionArgs spreads the reference's plugin, module and permission, so the check names the same declared permission a route guard would. Pass type yourself.
• Don't cache the moderator's answer for everyone. A response that depends on who asks must not go into a shared cache entry; cache the public part, then add the extras.

Refuse one optionCopy Anchor Link

assertStaffPermission takes the same arguments and throws 403 instead of returning false. Use it when a member asks for something only moderators may have, here the details behind ?details=1, while the plain request stays public:

import { assertStaffPermission } from "@vitnode/core/api/lib/check-staff-permission";

// request:
request: {
  params: z.object({ id: z.coerce.number().int().positive() }),
  query: z.object({ details: z.literal("1").optional() }), 
},

// handler, before reading the note:
const { details } = c.req.valid("query");
if (details) {
  await assertStaffPermission(c, {
    type: "moderator",
    ...staffPermissionArgs(staffPermissions.moderator.notes.canViewDetails),
  });
}

Call it before the handler reads or changes anything, so a refused request has no side effects. Add 403 to the route's responses too.

Moderator permissions can also be limited to some resources, such as some forum sections, with scope on the entry. Scoped moderator permissions covers the scope families and the AdminCP picker. moderatorStaffPermission and a check without a resource pass only for grants on all resources; to allow a moderator of one section, pass resource to checkStaffPermission or assertStaffPermission in the handler.

Content Engine content types declare their own permissions (can_view, can_create, can_edit, ...). Declaring the same module in defineStaffPermissions replaces them, so use your own module names for custom permissions. To guard a route with a content type's generated permission, see Content Engine permissions.