Roles and Permissions

Roles and Permissions

DataShield has a two-role model, enforced centrally in src/lib/apiAuth.ts. Every API route begins with one of two guards and returns its error when present:

const { session, error } = await requireAuth()   // any logged-in user
const { session, error } = await requireAdmin()  // ADMIN only
if (error) return error

The two roles

Role	Mandate	Can do
ADMIN	Configures the workspace	Manage API keys, directory connections, webhooks, plus everything a VIEWER can do
VIEWER	Operates the workspace	Read data, run scans, triage alerts, build dashboards and reports

New users default to VIEWER (the Prisma Role default).

Guard behaviour

• requireAuth() returns 401 { error: "Unauthorized" } when there is no session.
• requireAdmin() returns 401 when unauthenticated, and 403 { error: "Admin only" } when the session role is not ADMIN.

Which routes need ADMIN

ADMIN is required for configuration surfaces: credentials (/api/credentials), directory connections (/api/directory/*), and webhooks (/api/webhooks/*). Operational routes (scans, alert triage, dashboard config, presets, report export) accept any authenticated user. See API Reference for the per-endpoint matrix.

Tenancy boundary

Roles operate within a company. Every query is scoped to the session's companyId, so even an ADMIN only ever sees and manages their own tenant's data. See Database Schema for the multi-tenant model.