Roles and Permissions

define.wtf uses role-based access control (RBAC) to manage what team members can do. There are four roles organized in a hierarchy, with each role including all permissions of lower roles plus additional ones.

The Four Roles

1. Viewer

The most restricted role. Viewers can search, read, and vote, but cannot create or edit content.

Best for: Team members who need to look up terms but shouldn't contribute.

2. Editor

Can create and edit definitions, plus all Viewer permissions.

Best for: Active team members who contribute regularly to the dictionary.

3. Admin

Can manage content and team members, plus all Editor permissions.

Best for: Senior team members or department leads who oversee the dictionary.

4. Owner

Full control including workspace settings and team management.

Best for: Workspace administrators or company leadership.

Role Hierarchy

Roles are cumulative — each role includes all permissions of roles below it:

Owner
  ├── All Admin permissions
  ├── All Editor permissions
  └── All Viewer permissions

Admin
  ├── All Editor permissions
  └── All Viewer permissions

Editor
  └── All Viewer permissions

Viewer
  └── (most restricted)

Example: An Admin can do everything an Editor can do, plus additional admin tasks.

Complete Permission Table

This table shows all 28 permissions across the 4 roles:

View & Search Permissions (7 permissions)

Editing Permissions (4 additional permissions for Editor)

Admin Permissions (16 additional permissions for Admin)

Owner Permissions (1 additional for Owner)

Summary by Role

Viewer (7 permissions)

• View and search all acronyms
• Create new acronyms and definitions
• Vote on definitions (upvote/downvote)
• View and browse collections
• Cannot edit, delete, or manage anything

Use case: Employees who use the dictionary but don't maintain it.

Editor (11 permissions: 7 + 4)

All Viewer permissions, plus:

• Edit any acronym or definition (not just own)
• Delete definitions
• Set primary definitions
• Cannot delete acronyms or manage settings

Use case: Content maintainers who actively manage the dictionary.

Admin (27 permissions: 11 + 16)

All Editor permissions, plus:

• Delete and restore acronyms
• Lock/unlock and deprecate acronyms
• Create and manage collections and categories
• View team member list and change roles
• Manage webhooks, bulk import, and export
• Configure workspace settings (SSO, Slack, SCIM, etc.)
• Cannot delete or transfer the workspace

Use case: Team leads and senior admins who oversee the dictionary and team.

Owner (28 permissions: 27 + 1)

All Admin permissions, plus:

• Delete the entire workspace
• Transfer ownership
• Manage tenant-level settings

Use case: Workspace creator, company leadership, or designated account owner.

Permission Checks

Every API action checks permissions:

User requests: POST /api/v1/definitions
  ↓
System retrieves user's role
  ↓
System checks: does user have 'definition:create' permission?
  ✗ If no → return 403 Forbidden
  ✓ If yes → continue to next step
  ↓
System checks: is user allowed to edit THIS acronym?
  ✗ If no (e.g., acronym is locked) → return 409 Conflict
  ✓ If yes → allow operation
  ↓
Operation completes
  ↓
Audit logged

Examples

Example 1: Creating a Definition

Viewer tries to create a definition:

• Action: User clicks "Add Definition" on OKR page
• Permission check: Has definition:create? ✓ Yes
• Result: Definition is created successfully

Viewer sees another user's definition and wants to edit it:

• Action: User clicks "Edit" on someone else's definition
• Permission check: Has definition:edit_any? ✗ No (Viewers only have definition:edit_own)
• Result: "Edit" button is disabled or returns 403

Example 2: Changing a Definition to Primary

Editor wants to set a definition as primary:

• Action: Click "Set as Primary" on a definition
• Permission check: Has definition:set_primary? ✓ Yes
• Result: Definition is marked primary

Viewer tries the same action:

• Permission check: Has definition:set_primary? ✗ No
• Result: Button is disabled; returns 403 if attempted

Example 3: Deleting an Acronym

Admin wants to delete an acronym:

• Action: Click "Delete" on an acronym
• Permission check: Has acronym:delete? ✓ Yes
• Result: Acronym is soft-deleted (marked as deleted but data retained)

Editor tries to delete an acronym:

• Permission check: Has acronym:delete? ✗ No
• Result: No delete option appears; returns 403 if attempted

Example 4: Configuring SSO

Admin wants to set up SSO:

• Action: Go to Settings → SSO → Configure
• Permission check: Has tenant:manage_settings? ✓ Yes
• Result: Admin can configure SSO

Editor tries to access Settings:

• Permission check: Has tenant:manage_settings? ✗ No
• Result: Settings tab is not visible

Assigning Roles

Who Can Assign Roles?

Only Admins and Owners can assign roles (permission: user:change_role).

How to Assign a Role

1. Go to Settings → Members
2. Find the team member
3. Click their current role dropdown
4. Select new role (Viewer, Editor, Admin, Owner)
5. Changes take effect immediately

Role Change Scenarios

Onboarding a new team member:

1. They create account or are provisioned via SCIM
2. Default role is Viewer
3. Admin changes to Editor or appropriate role
4. User can now contribute to the dictionary

Promoting a contributor:

1. User has been Editor for a while
2. Admin changes role to Admin
3. User now has full admin capabilities

Restricting access:

1. Contractor's project ends
2. Admin changes role to Viewer (or removes user)
3. Contractor can no longer edit the dictionary

Special Cases

Deleted Users

When a user is deleted:

• Their account is deactivated
• They can no longer log in
• Their contributions remain (for audit purposes)
• Their role shows as "Inactive"

Soft Deletes vs. Hard Deletes

define.wtf uses soft deletes by default:

• Soft delete (default): Record marked as deleted_at = timestamp, but data retained
• Hard delete (admin only): Permanent removal from database

Most users only see soft delete options. Hard delete requires owner-level permission and explicit ?permanent=true parameter.

Locked Acronyms

Admins can lock acronyms to prevent further edits. Even Editors cannot edit locked acronyms (unless they're Admins themselves).

Deprecated Acronyms

Admins can mark acronyms as deprecated, signaling they're outdated but relevant for historical context. Users can still view deprecated acronyms but they appear with a deprecation notice.

Permissions in API

When you call the API, your role is verified:

# Viewer can search
curl -H "Authorization: Bearer TOKEN" \
  https://define.wtf/api/v1/acronyms?search=OKR

# Viewer tries to create (fails)
curl -X POST -H "Authorization: Bearer TOKEN" \
  https://define.wtf/api/v1/acronyms \
  -d '{"term": "KPI", "description": "..."}'
# Returns: 403 Forbidden - insufficient permissions

# Editor can create (succeeds)
curl -X POST -H "Authorization: Bearer TOKEN" \
  https://define.wtf/api/v1/acronyms \
  -d '{"term": "KPI", "description": "..."}'
# Returns: 201 Created

Permission Conflicts

If a user has multiple ways to access content:

Example: User is Editor and also owns a specific collection

• If they try to delete the collection: ✓ Allowed (as Editor with collection:delete)
• If they try to lock an acronym: ✗ Denied (Editors don't have acronym:lock)

The system uses the user's role-based permissions, not ownership.

Best Practices

For Admins Assigning Roles

• Start restrictive — Give new users Viewer role, promote as needed
• Match responsibilities — Editor for contributors, Admin for dictionary maintainers
• Document decisions — Make note of why users have specific roles
• Review quarterly — Audit user roles and permissions regularly
• Use SCIM groups — If using SCIM, map IdP groups to define.wtf roles automatically

For Users Understanding Their Role

• Know your permissions — Review the table above to understand what you can do
• Ask admins — If a feature is unavailable, ask why (you may need a higher role)
• Start as Viewer — If unsure, it's fine to start as Viewer and request promotion later
• Respect locks — If an acronym is locked, don't try to edit it (admins locked it intentionally)

See Also

• Admin Guide: Managing Users — Assign and manage roles
• Concepts: Audit Trail — See who changed what
• Integrations: SCIM — Auto-assign roles via IdP groups