# Improvado Roles API

**Canonical:** https://apis.io/apis/improvado/improvado-roles-api/  
**Provider:** Improvado — https://apis.io/providers/improvado/  
**Base URL:** https://embedded.improvado.io  
**Documentation:** https://developers.improvado.io/api

Improvado Roles API is one of 18 APIs that [Improvado](https://apis.io/providers/improvado/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Roles. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, authentication docs, and rate-limit docs.

Manage custom workspace roles and inspect the available permission catalog. Each agency ships with a fixed set of system roles (Workspace Admin, Editor, Viewer, Data Manager, Data Load Manager, Data Analyst). On top of these you can define **custom roles** scoped to the agency and assign them to users in any workspace. Capabilities: - List system + custom roles (each role carries its assigned `user_count`). - Fetch the curated permission catalog: a stable, ordered list of product layers with permissions, including human-readable `title` and `description` for each entry. - Create, rename, edit, and delete custom roles. System roles are read-only. - List users currently assigned to a role for impact preview. Delete semantics: deleting a custom role atomically reassigns every user holding it to the system **Viewer** role; the response returns `reassigned_users_count`. All Roles endpoints require an agency-chief Basic Auth credential and the `can_use_embedded_api` flag enabled for the agency.

## Operations (7)

| Method | Path | Summary |
|---|---|---|
| GET | `/api/v3/roles/` | List roles |
| POST | `/api/v3/roles/` | Create a custom role |
| GET | `/api/v3/roles/permissions` | Permissions catalog |
| GET | `/api/v3/roles/{role_id}` | Get a role |
| PATCH | `/api/v3/roles/{role_id}` | Update a custom role |
| DELETE | `/api/v3/roles/{role_id}` | Delete a custom role |
| GET | `/api/v3/roles/{role_id}/users` | List users assigned to a role |

## Machine-readable artifacts (6)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/improvado/refs/heads/main/openapi/improvado-roles-api-openapi.yml
- **Documentation** — https://improvado.io/llms.txt
- **LLMsTxt** — https://raw.githubusercontent.com/api-evangelist/improvado/refs/heads/main/llms/improvado-site-llms.txt
- **Authentication** — https://raw.githubusercontent.com/api-evangelist/improvado/refs/heads/main/authentication/improvado-authentication.yml
- **RateLimits** — https://raw.githubusercontent.com/api-evangelist/improvado/refs/heads/main/rate-limits/improvado-rate-limits.yml
- **ErrorCatalog** — https://raw.githubusercontent.com/api-evangelist/improvado/refs/heads/main/errors/improvado-error-codes.yml

## Other Improvado APIs (12)

- [Improvado Embedded API v3](https://apis.io/apis/improvado/improvado-embedded-api-v3/)
- [Improvado Customer MCP](https://apis.io/apis/improvado/improvado-customer-mcp/)
- [Improvado Accounts API](https://apis.io/apis/improvado/improvado-accounts-api/)
- [Improvado Authentication API](https://apis.io/apis/improvado/improvado-authentication-api/)
- [Improvado Automated Recipes API](https://apis.io/apis/improvado/improvado-automated-recipes-api/)
- [Improvado Data source connections API](https://apis.io/apis/improvado/improvado-data-source-connections-api/)
- [Improvado Data sources API](https://apis.io/apis/improvado/improvado-data-sources-api/)
- [Improvado Data tables API](https://apis.io/apis/improvado/improvado-data-tables-api/)
- [Improvado Destination connections API](https://apis.io/apis/improvado/improvado-destination-connections-api/)
- [Improvado Destinations API](https://apis.io/apis/improvado/improvado-destinations-api/)
- [Improvado Extraction templates API](https://apis.io/apis/improvado/improvado-extraction-templates-api/)
- [Improvado Extracts API](https://apis.io/apis/improvado/improvado-extracts-api/)

## Tags

Roles

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/improvado/improvado-roles-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/improvado/.