> For the complete documentation index, see [llms.txt](https://docs.ipaware.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipaware.io/dashboard/interactive-blocks.md). # 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:** | | *** ### 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