User Roles Reference¶

User roles define the base level of access and capabilities within TopTickets. This reference details each role's permissions and API key capabilities.

Available Roles¶

Role Details¶

Admin¶

Description: Full administrative access to the organization.

Capabilities:

• View, create, update, and delete all resources
• Manage users and teams
• Create API keys with any scopes
• View and revoke any API key in the organization
• Access all dashboard and reporting features

API Key Permissions:

Read-Only Admin¶

Description: Administrative visibility without write access.

Capabilities:

• View all resources (tickets, customers, users, teams)
• View dashboard and reports
• Create API keys (with restrictions)
• Cannot create, update, or delete resources

API Key Permissions:

Agent¶

Description: Standard support agent with full ticket management capabilities.

Capabilities:

• View, create, and update tickets
• Add comments and attachments to tickets
• View and manage customers
• View teams (cannot modify)
• Cannot manage users or organization settings

API Key Permissions:

Read-Only Agent¶

Description: View-only access for monitoring or reference purposes.

Capabilities:

• View tickets and comments
• View customers
• View teams and users
• Cannot create, update, or delete any resources

API Key Permissions:

Permissions Matrix¶

Resource Permissions by Role¶

Legend: C = Create, R = Read, U = Update, D = Delete

API Key Management by Role¶

API Key Prefix by Role¶

When API keys are created, they receive a prefix based on the creating user's role:

Role-Based API Behavior¶

Creating Resources¶

When creating resources via API:

• Admins: Full access with any API key scopes
• Read-Only Admins: Cannot create via API (read-only scopes only)
• Agents: N/A (cannot create API keys)
• Read-Only Agents: N/A (cannot create API keys)

Viewing Resources¶

All roles can view resources within their organization:

# Any valid API key with appropriate read scope
response = requests.get(
    f"{BASE_URL}/tickets",
    headers={"Authorization": f"Bearer {api_key}"}
)

Scope Restrictions¶

Read-Only Admin keys are restricted to read-only scopes:

# This will fail for Read-Only Admin
response = requests.post(
    f"{BASE_URL}/api-keys",
    headers=HEADERS,
    json={
        "name": "My Key",
        "scopes": ["tickets:write"]  # Error: not allowed for read-only admin
    }
)

Allowed scopes for Read-Only Admin:

[
  "tickets:read",
  "comments:read",
  "attachments:read",
  "customers:read",
  "teams:read",
  "users:read",
  "dashboard:read"
]

Changing Roles¶

User roles can be changed by Admin users:

# Admin updating a user's role
response = requests.patch(
    f"{BASE_URL}/users/{user_id}",
    headers=HEADERS,
    json={"role": "agent"}
)

Use Cases¶

Admin Role¶

• Organization administrators
• System integrations requiring full access
• DevOps and infrastructure management

Read-Only Admin Role¶

• Managers needing visibility without risk
• Compliance and audit personnel
• Reporting and analytics users
• Temporary access for consultants

Agent Role¶

• Front-line support staff
• Customer success managers
• Technical support engineers

Read-Only Agent Role¶

• New employees in training
• Quality assurance reviewers
• Executive oversight
• External partners needing visibility

Best Practices¶

1. Start with Least Privilege¶

Assign the most restrictive role that allows users to do their job:

Read-Only Agent → Agent → Read-Only Admin → Admin

2. Use Read-Only Admin for Integrations¶

For read-only integrations (dashboards, reporting), use Read-Only Admin keys with enforced expiration for added security.

3. Audit Role Assignments¶

Regularly review user roles and downgrade when full access is no longer needed.

4. Document Role Requirements¶

Clearly document which roles are required for different functions to avoid over-provisioning.