Roles & Permissions

Control access to your organization with granular role-based permissions. Create custom roles tailored to your team's needs.

Overview

Roles define what actions users and API keys can perform. Each role contains a set of permissions that grant specific capabilities. Key Concepts:

• Roles: Named collections of permissions (e.g., "Admin", "Read-only")

• Permissions: Specific actions (e.g., api.key.create, organization.invite)

• Assignment: Roles can be assigned to team members and API keys

• Inheritance: Users can have multiple roles; permissions are combined

---

System Roles

Built-in roles cannot be edited or deleted. For example:

Organization Owner

• Type: Global (system-managed)

• Description: Full control over the organization

• Permissions: All permissions

• Assignment: Automatically assigned to organization creator

• Limit: One per organization

• Transfer: Via ownership transfer feature

Organization Admin

• Manage organization settings

• Invite and remove members

• Create and manage API keys

• View billing information

• Cannot transfer ownership

Organization Member

• View organization resources

• Use assigned API keys

• View usage statistics

• Limited management capabilities

---

Custom Roles

Create roles specific to your organization's needs.

Creating a Role

Steps:

1. Open Creation Modal

   • Navigate to the Roles tab

   • Click + Create Role

2. Enter Basic Information

   • Role Name: Descriptive name (e.g., "Read-only Analyst")

   • Description: Optional explanation of the role's purpose

3. Select Permissions

   • Permissions are grouped by category

   • Check the boxes for permissions you want to include

   • See Permission Groups below for details

4. Save Role

   • Click Create Role

   • Role appears in the roles table

   • Can now be assigned to members and API keys

Editing a Role

Modify existing custom roles:

Steps:

1. Find the role in the table

2. Click Edit

3. Update the name, description, or permissions

4. Click Save Changes

Effects:

• Changes apply immediately to all users/keys with this role

• Users are not notified of permission changes

• Consider communicating major changes to affected users

Note: You cannot edit system roles (they show a "View" button instead).

Viewing a Role

Inspect system roles or review custom roles:

Steps:

1. Click View next to a system role (or Edit for custom roles)

2. See all assigned permissions

3. Permissions are grouped by category

4. Click Close when done

Deleting a Role

Remove custom roles that are no longer needed:

Steps:

1. Click Delete next to the role

2. Confirm the action Requirements:

• Role must not be assigned to any users or API keys

• Cannot delete system roles

Effects:

• Role is permanently removed

• Cannot be undone

---

Permission Groups

Permissions are organized into logical categories:

Permissions

• permissions.view - View system permissions

Roles

• roles.create - Create custom roles

• roles.view - View roles and permissions

• roles.update - Edit custom roles

• roles.delete - Delete custom roles

• roles.assign - Assign roles to members

• roles.revoke - Remove roles from members

Organization

• organization.view - View organization details

• organization.update - Edit organization information

• organization.invite - Send invitations to new members

• organization.remove - Remove members from organization

• organization.whitelist.view - View whitelisted IPs

• organization.whitelist.manage - Manage whitelisted IP labels

API Keys

• api.key.create - Create new API keys

• api.key.view - View API key list and details

• api.key.update - Edit API key names and roles

• api.key.revoke - Revoke API keys

Billing

• billing.checkout - Create a checkout session

• billing.portal - View subscription and payment information

• billing.update - Change plans and payment methods

• billing.cancel - Cancel subscriptions

• billing.resume - Cancel subscriptions

IP

• ip.query - Query IP addresses

---

Roles Table

The roles table displays all available roles:

Column	Description
Role Name	Display name of the role
Description	Purpose and usage notes
Permissions	Count of assigned permissions
Type	Global (system) or Custom
Actions	View, Edit, or Delete buttons
Type Badges:	Global (Yellow) - System role, cannot be edited Custom (Green) - Organization-specific, can be edited

---

Best Practices

Role Design

Keep it simple:

• Create roles for common job functions

• Avoid creating too many similar roles

• Use clear, descriptive names

Principle of least privilege:

• Grant only necessary permissions

• Start with minimal access

• Add permissions as needed

Document roles:

• Use the description field

• Maintain external documentation

• Explain when to use each role

Permission Management

Regular audits:

• Review roles quarterly

• Remove unused roles

• Verify permissions are still appropriate

Testing:

• Test new roles with a test account

• Verify permissions work as expected

• Check for unintended access

Communication:

• Inform users of role changes

• Document permission requirements

• Provide role assignment guidelines

---

Assigning Roles

To Team Members

See Team Management for details on assigning roles to users.

Quick steps:

1. Go to Team tab

2. Click Manage Roles next to a member

3. Select and assign roles

To API Keys

See API Keys for details on assigning roles to keys.

Quick steps:

1. Go to API Keys tab

2. When creating or editing a key, select a role

3. Save the key

---

Troubleshooting

Can't Create Role

Possible causes:

• Don't have roles.create permission

• Role name already exists

• No permissions selected

Solutions:

• Ask an Owner or Admin for permission

• Choose a unique role name

• Select at least one permission

Can't Delete Role

Possible causes:

• Role is assigned to users or API keys

• Trying to delete a system role

Solutions:

• Remove role from all users and keys first

• System roles cannot be deleted

Permission Not Working

Check:

• User/key has the role assigned

• Role includes the required permission

• Permission is spelled correctly

• Changes have been saved

---

Permissions Required

To manage roles, you need:

• Create roles: roles.create

• Edit roles: roles.update

• Delete roles: roles.delete

• View roles: roles.view

• Assign roles: roles.assign

• Revoke roles: roles.revoke

---

Next Steps

• Assign roles to team members

• Create API keys with specific roles

• Review organization permissions