Understanding User Roles and Permission Levels
Learn how Admin manages access control through roles, permission levels, and hierarchical authorization to keep your workspace secure and organized.
Introduction
Admin uses a role-based access control (RBAC) model to manage who can see, create, edit, and delete resources within your organization. By assigning users to predefined roles or creating custom permission sets, you ensure that each team member has exactly the access they need — and nothing more.
Key Concept
Every user must have at least one role. Permissions are additive — if a user holds multiple roles, they inherit the union of all permissions from each role.
Core Principles
- Principle of Least Privilege: Users receive only the permissions necessary to perform their job functions.
- Role Inheritance: Higher-level roles automatically include all permissions from lower levels, unless explicitly restricted.
- Granular Control: Permissions can be scoped to specific projects, folders, or individual resources.
- Audit Trail: All permission changes are logged and can be reviewed in the Audit Logs.
Role Hierarchy Overview
Admin provides five built-in roles, each with increasing levels of access. Below is a summary of each role and its core responsibilities.
Super Admin
Level 5 — Full AccessComplete control over the organization. Can manage billing, delete workspaces, and override any restriction.
Manager
Level 4 — Admin AccessManages team members, projects, and workspace settings. Cannot access billing or delete the organization.
Editor
Level 3 — Content AccessCreates and edits content, manages projects assigned to them, and collaborates with the team.
Viewer
Level 2 — Read OnlyRead-only access to assigned projects and shared resources. Cannot create, edit, or delete anything.
Custom Role
Variable — Tailored AccessA bespoke permission set created by Super Admins or Managers to fit unique team requirements.
Complete Permission Matrix
The table below provides a detailed breakdown of every permission category and which roles have access. Hover over rows for more details.
| Permission Category | Super Admin | Manager | Editor | Viewer | Custom |
|---|---|---|---|---|---|
| View All Data Access all projects and resources |
✓ | ✓ | Scoped | Scoped | Config |
| Edit & Delete Content Modify or remove records |
✓ | ✓ | ✓ | ✗ | Config |
| Create Projects Initialize new projects |
✓ | ✓ | ✓ | ✗ | Config |
| Manage Users Invite, remove, modify roles |
✓ | ✓ | ✗ | ✗ | Config |
| Workspace Settings Configure global preferences |
✓ | ✓ | ✗ | ✗ | Config |
| Billing & Subscriptions Plans, invoices, payments |
✓ | ✗ | ✗ | ✗ | ✗ |
| API Key Management Create and revoke keys |
✓ | ✓ | ✗ | ✗ | Config |
| Audit Log Access View activity history |
✓ | ✓ | ✗ | ✗ | Config |
| Export Data Download reports & backups |
✓ | ✓ | ✓ | ✗ | Config |
| Delete Workspace Permanently remove organization |
✓ | ✗ | ✗ | ✗ | ✗ |
Important: Billing Access is Restricted
For security reasons, only Super Admins can access billing and subscription settings. This cannot be overridden by custom roles. Contact Admin support if you need to delegate billing oversight.
How to Assign Roles to Users
Follow these steps to assign or modify a user's role within your Admin workspace.
Navigate to Team Settings
Go to Settings → Team Management from the left sidebar. You'll see a list of all active and pending members.
Select a Team Member
Click on the user's name to open their profile card. Here you can view their current role, assigned projects, and activity history.
Choose or Create a Role
Use the role dropdown to select a built-in role, or click "Create Custom Role" to define a new permission set.
Set Scope (Optional)
For Editors and Viewers, you can limit access to specific projects or folders. Leave empty for workspace-wide access.
Save & Notify
Click "Update Role". The user will receive an email notification about their permission changes. Changes take effect immediately.
Creating Custom Roles
Custom roles let you define precise permission sets that don't fit the built-in options. They're ideal for specialized positions like auditors, interns, or external consultants.
Custom Role Builder
The role builder provides a checkbox-based interface organized by permission categories:
| Permission Group | Available Permissions | Example Use Case |
|---|---|---|
| Data Access | View All, View Assigned, Edit Own, Edit All, Delete Own, Delete All | Grant a contractor view-only access to a single project |
| Project Management | Create, Archive, Transfer Ownership, Delete | Allow a lead developer to create and manage projects without user admin |
| Team Management | Invite Users, Remove Users, Assign Roles, View Directory | Let an HR manager invite new team members without seeing data |
| System | API Keys, Webhooks, Integrations, Audit Logs, Exports | Give a DevOps engineer API key access without content editing |
| Temporal | Set Expiry Date, Session Timeout, IP Restriction | Create a temporary role for a 30-day audit with auto-expiry |
Pro Tip: Use Temporal Roles
Custom roles support auto-expiry. Set an end date and the role will be automatically revoked, reducing the risk of orphaned access. Perfect for contractors, interns, and temporary projects.
Managing Roles via API
You can also assign and manage roles programmatically using Admin's REST API. This is useful for automated onboarding workflows or integrating with HR systems.
Assign a Role to a User
POST /api/v3/users/:id/roles
{
"role_id": "editor",
"scope": {
"projects": ["proj_abc123", "proj_def456"],
"expires_at": "2025-06-30T23:59:59Z"
},
"notify_user": true
}
Retrieve Current User's Permissions
GET /api/v3/users/me/permissions
{
"roles": [
{
"id": "editor",
"name": "Editor",
"level": 3
}
],
"effective_permissions": [
"data:read",
"data:write",
"projects:create"
],
"scoped_to": ["proj_abc123"]
}
Best Practices
Follow these guidelines to maintain a secure and efficient permission structure:
| Practice | Why It Matters | How to Implement |
|---|---|---|
| Audit Quarterly | Prevents permission creep as teams change | Review Audit Logs every 90 days; remove unused accounts |
| Default to Lowest Role | Minimizes accidental data exposure | Start new users as Viewers; escalate as needed | d>
| Limit Super Admins | Reduces blast radius of compromised accounts | Keep no more than 2–3 Super Admins per workspace |
| Use Scope Over Promotion | More granular control than escalating roles | Scope an Editor to specific projects instead of making them a Manager |
| Document Custom Roles | Ensures consistency and onboarding clarity | Add descriptions and purpose notes to each custom role |
Frequently Asked Questions
Settings → Audit Logs). Each entry includes the timestamp, the user who made the change, the previous role, the new role, and the affected user. Audit logs are immutable and cannot be edited or deleted.