Staff API

pleate_backend.staff is the API behind a back office: users, their roles and sessions, IP bans and the numbers for a dashboard. Build the screens with DataTable, StatCard and useList; the Django admin stays available for everything else.

Every endpoint needs is_staff or the matching model permission, which can be granted through a role: pleate_accounts.view_user, change_user and delete_user for users and stats, pleate_staff.*_ban for bans. A support role can therefore read users without being staff. These endpoints need a signed in session: an API key is refused with api_key_not_allowed, even for a superuser.

Only a superuser can change, sign out or delete another staff account or a superuser. Without superuser rights, roles can only add or remove roles whose permissions you hold yourself, and never your own.

Endpoints

Mounted at /api/staff.

User list items: id, email, name, display_name, avatar_url, email_verified, is_active, is_staff, is_superuser, date_joined, last_login, roles. signups_by_day covers 30 days, oldest first, as [{date, count}]; users_active counts accounts that are not deactivated.

A users screen

const users = useList<StaffUser>("/staff/users", { ordering: "-date_joined", syncUrl: true });
const client = usePleateClient();

<DataTable
  aria-label="Users"
  columns={columns}
  getRowId={(u) => u.id}
  {...users.tableProps}
  toolbar={
    <SegmentedControl
      size="sm"
      value={String(users.filters.is_active ?? "all")}
      onValueChange={(v) => users.setFilter("is_active", v === "all" ? undefined : v)}
      options={[{ value: "all", label: "All" }, { value: "true", label: "Active" }, { value: "false", label: "Deactivated" }]}
    />
  }
  onRowClick={(u) => router.push(`/admin/users/${u.id}`)}
/>

await client.staff.updateUser(id, { is_active: false, roles: ["support"] });

const stats = useQuery({ queryKey: ["staff", "stats"], queryFn: client.staff.stats });

<StatCard label="Users" value={stats.data?.users_total ?? 0} />
<StatCard label="New this week" value={stats.data?.users_new_7d ?? 0} />
<StatCard label="Signed in now" value={stats.data?.sessions_active ?? 0} />

IP bans

BanMiddleware answers 403 banned to clients whose address is in an active ban, using client_ip (so X-Forwarded-For from trusted proxies). /api/health is never blocked. Active networks are cached for 25 seconds in the Django cache and 5 seconds in each process; saving or deleting a ban drops both, so a warm request makes no database query. If the cache is down, requests pass.

from pleate_backend.staff.bans import is_banned, invalidate
from pleate_backend.staff.models import Ban

is_banned("203.0.113.24")      # True or False
Ban.objects.active()           # bans that have not expired

Error codes