> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/connect/n8n-api/role.md).

# Role

Operations about roles

## Retrieve all roles

> Returns all roles grouped by type (global and project). Set \`withUsageCount\` to include how many users and projects use each role.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Role","description":"Operations about roles"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/roles":{"get":{"operationId":"getAllRoles","tags":["Role"],"summary":"Retrieve all roles","description":"Returns all roles grouped by type (global and project). Set `withUsageCount` to include how many users and projects use each role.","parameters":[{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"name":"withUsageCount","in":"query"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"global":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string","nullable":true},"systemRole":{"type":"boolean"},"roleType":{"type":"string","enum":["global"]},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"licensed":{"type":"boolean"},"usedByUsers":{"type":"number"},"usedByProjects":{"type":"number"}},"required":["slug","displayName","description","systemRole","roleType","scopes","createdAt","updatedAt","licensed"]}},"project":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string","nullable":true},"systemRole":{"type":"boolean"},"roleType":{"type":"string","enum":["project"]},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"licensed":{"type":"boolean"},"usedByUsers":{"type":"number"},"usedByProjects":{"type":"number"}},"required":["slug","displayName","description","systemRole","roleType","scopes","createdAt","updatedAt","licensed"]}}},"required":["global","project"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"}}}}}}
```

## Create a custom role

> Creates a custom role. Set \`roleType\` to \`global\` for an instance-wide role or \`project\` for a project role.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Role","description":"Operations about roles"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"schemas":{"rolePublicDto.generated":{"type":"object","properties":{"slug":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string","nullable":true},"systemRole":{"type":"boolean"},"roleType":{"type":"string","enum":["project","global"]},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["slug","displayName","description","systemRole","roleType","scopes","createdAt","updatedAt"]}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/roles":{"post":{"operationId":"createRole","tags":["Role"],"summary":"Create a custom role","description":"Creates a custom role. Set `roleType` to `global` for an instance-wide role or `project` for a project role.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":2,"maxLength":100},"description":{"type":"string","maxLength":500},"roleType":{"type":"string","enum":["project","global"]},"scopes":{"type":"array","items":{"type":"string"}}},"required":["displayName","roleType","scopes"]}}}},"responses":{"201":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rolePublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"}}}}}}
```

## Retrieve a role

> Returns a single role with its scopes. Set \`withUsageCount\` to include how many users and projects use the role.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Role","description":"Operations about roles"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/roles/{slug}":{"get":{"operationId":"getRole","tags":["Role"],"summary":"Retrieve a role","description":"Returns a single role with its scopes. Set `withUsageCount` to include how many users and projects use the role.","parameters":[{"schema":{"type":"string"},"required":true,"name":"slug","in":"path"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"name":"withUsageCount","in":"query"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string","nullable":true},"systemRole":{"type":"boolean"},"roleType":{"type":"string","enum":["project","global"]},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"licensed":{"type":"boolean"},"usedByUsers":{"type":"number"},"usedByProjects":{"type":"number"}},"required":["slug","displayName","description","systemRole","roleType","scopes","createdAt","updatedAt","licensed"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Update a custom role

> Replaces a custom role's display name, description, and scopes. System roles cannot be updated.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Role","description":"Operations about roles"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"schemas":{"rolePublicDto.generated":{"type":"object","properties":{"slug":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string","nullable":true},"systemRole":{"type":"boolean"},"roleType":{"type":"string","enum":["project","global"]},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["slug","displayName","description","systemRole","roleType","scopes","createdAt","updatedAt"]}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/roles/{slug}":{"put":{"operationId":"updateRole","tags":["Role"],"summary":"Update a custom role","description":"Replaces a custom role's display name, description, and scopes. System roles cannot be updated.","parameters":[{"schema":{"type":"string"},"required":true,"name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":2,"maxLength":100},"description":{"type":"string","nullable":true,"maxLength":500},"scopes":{"type":"array","items":{"type":"string"}}},"required":["displayName","description","scopes"]}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rolePublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```