--- title: How Do I Interact with Roles via API? description: This article explains how Roles are structured and the entities that can be configured via API. --- [Skip to content](https://kb.edgescan.com/knowledge/how-do-i-interact-with-roles-via-api#main-content) English Show submenu for translations [![Edgescan Cybersecurity Platform | EASM + RBVM + PTaaS](https://kb.edgescan.com/hs-fs/hubfs/Logos/23LOGOS-thicker/Edgescan-Logo-Black.png?width=200&height=40&name=Edgescan-Logo-Black.png)](https://www.edgescan.com/) Open main navigation Close main navigation - English Show submenu for translations Search the Edgescan knowledge base - There are no suggestions because the search field is empty. 1. [Help Center](https://kb.edgescan.com/knowledge?hsLang=en) 2. [Organization Administration](https://kb.edgescan.com/knowledge/organization-administration?hsLang=en) 3. [Account Settings](https://kb.edgescan.com/knowledge/organization-administration?hsLang=en#account-settings) # How Do I Interact with Roles via API? ## This article explains how Roles are structured and the entities that can be configured via API. Version Number: v1.0.0 Published Date: 25 May 2026 \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ The Roles functionality is currently in BETA, we expect this functionality to be available to all customers in Q1 2026. #### What are these Entities? - **Roles**: Named “bundles” of access rules (for example: *Auditor*, *Admin*, *Read-only*). - **Role permissions**: The actual “what a role can do” entries inside a role (what resource/action/value is allowed, plus how broadly it applies). - **User role assignments**: The link between a **user** and a **role** (assign/unassign users to roles). Below are the available endpoints **User APIs**. #### Permission names (the key ones you’ll see) - `assign_role`: Allows assigning/unassigning roles to users. - plus the action permission on the role: `create`, `edit`, or `delete` - For **editing role permissions**, the permission you need is effectively **“edit this role”**: - User API: requires `edit` on the role - For **viewing** a specific role-permission entry (User API show), it requires `view` on the role. For more info, please check out the [User Permissions Map](https://kb.edgescan.com/knowledge/what-permissions-are-available-to-users-via-a-permissions-matrix?hsLang=en) #### User APIs (`/api/v1`) ### Roles All paths are under: `/api/v1/roles...` - `GET /api/v1/roles.json` - **What it does**: Lists roles visible to the signed-in user. - **Permissions needed**: Role visibility. - `GET /api/v1/roles/:id.json` - **What it does**: Returns one role. - **Permissions needed**: Role visibility. - `POST /api/v1/roles.json` - **What it does**: Creates an **organization-scoped** role (user API does not create global roles). - **Permissions needed**: `create` on roles for the target owning organization. - `PUT /api/v1/roles/:id.json` - **What it does**: Updates role name/description. - **Permissions needed**: `edit` on the role (and `create` on roles for its owner org). - `DELETE /api/v1/roles/:id.json` - **What it does**: Deletes a role (only if not assigned to users). - **Permissions needed**: `delete` on the role. ### Role permissions (inside a role) All paths are under: `/api/v1/roles/:role_id/role_permissions...` - `GET /api/v1/roles/:role_id/role_permissions.json` - **What it does**: Lists role permission entries. - **Permissions needed**: Must be allowed to view the role. - `GET /api/v1/roles/:role_id/role_permissions/:id.json` - **What it does**: Returns one role permission entry. - **Permissions needed**: `view` on the role. - `POST /api/v1/roles/:role_id/role_permissions.json` - **What it does**: Adds a permission entry. - **Permissions needed**: `edit` on the role. - `PUT /api/v1/roles/:role_id/role_permissions/:id.json` - **What it does**: Updates a permission entry. - **Permissions needed**: `edit` on the role. - `DELETE /api/v1/roles/:role_id/role_permissions/:id.json` - **What it does**: Removes a permission entry. - **Permissions needed**: `edit` on the role. - `PUT /api/v1/roles/:role_id/role_permissions/bulk_update.json` - **What it does**: Bulk create/update permission entries. - **Permissions needed**: `edit` on the role. - `POST /api/v1/roles/:role_id/role_permissions/bulk_delete.json` - **What it does**: Bulk delete by ids. - **Permissions needed**: `edit` on the role. **Role permission payload difference (User API)** - User roles can use `scope_strategy` only from: `user_org`, `resource`, `role_owner` (no `global`). ### User role assignments All paths are under: `/api/v1/users/:user_id/role_assignments...` - `GET /api/v1/users/:user_id/role_assignments.json` - **What it does**: Lists roles assigned to the user. - **Permissions needed**: Must be allowed to view that user. - `POST /api/v1/users/:user_id/role_assignments.json` - **What it does**: Assign a role (pass `role_id`). - **Permissions needed**: `assign_role` on the target user. - `POST /api/v1/users/:user_id/role_assignments/unassign_role.json` - **What it does**: Unassign a role (pass `role_id`). - **Permissions needed**: `assign_role` on the target user. - `DELETE /api/v1/users/:user_id/role_assignments/:id.json` - **What it does**: Removes one role assignment record. - **Permissions needed**: `assign_role` on the target user. - [Getting Started](https://kb.edgescan.com/knowledge/getting-started?hsLang=en#main-content) - [Quick Start](https://kb.edgescan.com/knowledge/getting-started?hsLang=en#quick-start) - [Prerequisites & Network Requirements](https://kb.edgescan.com/knowledge/getting-started?hsLang=en#prerequisites-network-requirements) - [Compliance Context](https://kb.edgescan.com/knowledge/getting-started?hsLang=en#compliance-context) - [Attack Surface Management](https://kb.edgescan.com/knowledge/attack-surface-management?hsLang=en#main-content) - [Concepts](https://kb.edgescan.com/knowledge/attack-surface-management?hsLang=en#concepts) - [Discovery Methods](https://kb.edgescan.com/knowledge/attack-surface-management?hsLang=en#discovery-methods) - [Asset Inventory](https://kb.edgescan.com/knowledge/attack-surface-management?hsLang=en#asset-inventory) - [Vulnerability Scanning](https://kb.edgescan.com/knowledge/vulnerability-scanning?hsLang=en#main-content) - [Enabling & Disabling Scanning](https://kb.edgescan.com/knowledge/vulnerability-scanning?hsLang=en#enabling-disabling-scanning) - [Scope & Targeting](https://kb.edgescan.com/knowledge/vulnerability-scanning?hsLang=en#scope-targeting) - [Setting Authentication](https://kb.edgescan.com/knowledge/vulnerability-scanning?hsLang=en#setting-authentication) - [DAST Scanning](https://kb.edgescan.com/knowledge/vulnerability-scanning?hsLang=en#dast-scanning) - [API Settings](https://kb.edgescan.com/knowledge/vulnerability-scanning?hsLang=en#api-settings) - [Scanning Complex Workflows](https://kb.edgescan.com/knowledge/vulnerability-scanning?hsLang=en#scanning-complex-workflows) - [Vulnerability Risk Ratings](https://kb.edgescan.com/knowledge/vulnerability-scanning?hsLang=en#vulnerability-risk-ratings) - [Additional Configurations](https://kb.edgescan.com/knowledge/vulnerability-scanning?hsLang=en#additional-configurations) - [Agentic PTaaS](https://kb.edgescan.com/knowledge/agentic-ptaas?hsLang=en#main-content) - [Overviews and Concepts](https://kb.edgescan.com/knowledge/agentic-ptaas?hsLang=en#overviews-and-concepts) - [Using Atomic](https://kb.edgescan.com/knowledge/agentic-ptaas?hsLang=en#using-atomic) - [Safety and Privacy](https://kb.edgescan.com/knowledge/agentic-ptaas?hsLang=en#safety-and-privacy) - [Human PTaaS](https://kb.edgescan.com/knowledge/human-ptaas?hsLang=en#main-content) - [Concepts & Methodologies](https://kb.edgescan.com/knowledge/human-ptaas?hsLang=en#concepts-methodologies) - [Scheduling PTaaS](https://kb.edgescan.com/knowledge/human-ptaas?hsLang=en#scheduling-ptaas) - [Platform Usage](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#main-content) - [Platform Navigation](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#platform-navigation) - [Managing Assets](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#managing-assets) - [Managing Vulnerabilities](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#managing-vulnerabilities) - [Managing Licenses](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#managing-licenses) - [Managing Credentials](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#managing-credentials) - [Asset Blockers](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#asset-blockers) - [Reporting & Dashboards](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#reporting-dashboards) - [AI Insights](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#ai-insights) - [Compliance & Frameworks](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#compliance-frameworks) - [Additional License Details](https://kb.edgescan.com/knowledge/platform-usage?hsLang=en#additional-license-details) - [Platform Automation](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#main-content) - [Notifications & Events](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#notifications-events) - [Internal/Private Testing](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#internal-private-testing) - [API & Authentication](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#api-authentication) - [Scheduled Exports](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#scheduled-exports) - [Cloud Platforms](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#cloud-platforms) - [CloudHook](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#cloudhook) - [ITSM & Ticketing](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#itsm-ticketing) - [SIEM & SOAR](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#siem-soar) - [CI/CD & DevOps](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#ci-cd-devops) - [Communication Automation](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#communication-automation) - [Other Automations](https://kb.edgescan.com/knowledge/platform-automation?hsLang=en#other-automations) - [Organization Administration](https://kb.edgescan.com/knowledge/organization-administration?hsLang=en#main-content) - [Organization Setup](https://kb.edgescan.com/knowledge/organization-administration?hsLang=en#organization-setup) - [User Administration](https://kb.edgescan.com/knowledge/organization-administration?hsLang=en#user-administration) - [Roles Administration](https://kb.edgescan.com/knowledge/organization-administration?hsLang=en#roles-administration) - [Account Settings](https://kb.edgescan.com/knowledge/organization-administration?hsLang=en#account-settings) - [Organization Settings](https://kb.edgescan.com/knowledge/organization-administration?hsLang=en#organization-settings) - [Updates & Announcements](https://kb.edgescan.com/knowledge/updates-announcements?hsLang=en#main-content) - [2026 Updates](https://kb.edgescan.com/knowledge/updates-announcements?hsLang=en#2026-updates) - [2025 Updates](https://kb.edgescan.com/knowledge/updates-announcements?hsLang=en#2025-updates) - [2024 Updates](https://kb.edgescan.com/knowledge/updates-announcements?hsLang=en#2024-updates) - [2023 Updates](https://kb.edgescan.com/knowledge/updates-announcements?hsLang=en#2023-updates) - [API Changes](https://kb.edgescan.com/knowledge/updates-announcements?hsLang=en#api-changes) - [OWASP API 2019](https://kb.edgescan.com/knowledge/updates-announcements?hsLang=en#owasp-api-2019) [![Chill listening crop-3](https://kb.edgescan.com/hs-fs/hubfs/Edgescan-blac-logo.webp?width=68&height=55&name=Edgescan-blac-logo.webp "Chill listening crop-3")](https://www.edgescan.com) Copyright © 2026 Edgescan. All rights reserved.