> 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 ### 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ipaware.io/dashboard/interactive-blocks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.