Users, Roles, and Permissions
Guardhouse manages the people who can authenticate to your identity system and provides roles and permissions for organizing their access.
Users
A user is a human identity in the tenant. Guardhouse owns the authentication lifecycle, including the configured sign-in methods and account security features. Your application should use the stable subject identifier from the authenticated identity as its external user key rather than treating an editable email address as the primary key.
Roles
A role groups access for a job or responsibility, such as support-agent or billing-admin. Users can be assigned to roles so the assignment can be managed centrally.
Prefer roles that describe responsibilities. Avoid creating a separate role for every route or UI element.
Permissions
A permission represents a more specific capability. Permissions can be added to and removed from roles. This lets applications express checks more precisely while administrators assign a manageable set of roles to users.
Where Authorization Happens
Guardhouse stores the identity and authorization model, but the receiving application remains the enforcement point. It must validate the access token and apply an explicit rule at the API boundary.
Do not assume that every user, role, or permission record is automatically present in every token. Enforce only claims and scopes actually issued for the configured client and flow, or retrieve the required data through an appropriate trusted integration.
Return:
401 Unauthorizedwhen authentication is missing or invalid403 Forbiddenwhen the caller is authenticated but lacks the required access
Administration Options
Use the Guardhouse dashboard for interactive administration. Use the privileged /api/v1 System API to automate supported user, role, and permission operations from a trusted backend.
The system_api scope grants broad administrative access. It belongs only in a confidential backend client and must never be exposed to an end-user application.