> 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-mapping-rule.md).

# Role Mapping Rule

Operations about identity-provider role-mapping rules

## Retrieve role-mapping rules

> Returns the configured role-mapping rules. \`order\` is the rule's evaluation position within its own \`type\`, so instance and project rules each have their own sequence starting at 0 — filter by \`type\` to retrieve a single evaluation order.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"RoleMappingRule","description":"Operations about identity-provider role-mapping rules"}],"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"}},"parameters":{"limit":{"name":"limit","in":"query","description":"The maximum number of items to return.","required":false,"schema":{"type":"number","default":100,"maximum":250}},"cursor":{"name":"cursor","in":"query","description":"Paginate by setting the cursor parameter to the nextCursor attribute returned by the previous request's response. Default value fetches the first \"page\" of the collection. See pagination for more detail.","required":false,"style":"form","schema":{"type":"string"}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/role-mapping-rules":{"get":{"operationId":"getRoleMappingRules","tags":["RoleMappingRule"],"summary":"Retrieve role-mapping rules","description":"Returns the configured role-mapping rules. `order` is the rule's evaluation position within its own `type`, so instance and project rules each have their own sequence starting at 0 — filter by `type` to retrieve a single evaluation order.","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"schema":{"type":"string","enum":["instance","project"]},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"expression":{"type":"string"},"role":{"type":"string"},"type":{"type":"string","enum":["instance","project"]},"order":{"type":"integer"},"projectIds":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","expression","role","type","order","projectIds","createdAt","updatedAt"]}},"nextCursor":{"type":"string","nullable":true}},"required":["data","nextCursor"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"}}}}}}
```

## Create a role-mapping rule

> Creates a rule that maps an identity-provider claim expression to a role. Set \`type\` to \`instance\` for a rule granting a global role, or \`project\` for a rule granting a project role on the projects named in \`projectIds\`. Omitting \`order\` appends the rule to the end of the evaluation order for its type.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"RoleMappingRule","description":"Operations about identity-provider role-mapping rules"}],"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":{"roleMappingRulePublicDto.generated":{"type":"object","properties":{"id":{"type":"string"},"expression":{"type":"string"},"role":{"type":"string"},"type":{"type":"string","enum":["instance","project"]},"order":{"type":"integer"},"projectIds":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","expression","role","type","order","projectIds","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."},"unsupportedMediaType":{"description":"Unsupported media type."}}},"paths":{"/role-mapping-rules":{"post":{"operationId":"createRoleMappingRule","tags":["RoleMappingRule"],"summary":"Create a role-mapping rule","description":"Creates a rule that maps an identity-provider claim expression to a role. Set `type` to `instance` for a rule granting a global role, or `project` for a rule granting a project role on the projects named in `projectIds`. Omitting `order` appends the rule to the end of the evaluation order for its type.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expression":{"type":"string","minLength":1},"role":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["instance","project"]},"order":{"type":"integer","minimum":0},"projectIds":{"type":"array","items":{"type":"string"}}},"required":["expression","role","type"]}}}},"responses":{"201":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/roleMappingRulePublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"415":{"$ref":"#/components/responses/unsupportedMediaType"}}}}}}
```

## Move a role-mapping rule

> Changes a rule's position in the evaluation order for its type. \`targetIndex\` is the desired 0-based position within the rule's own \`type\` sequence; a value beyond the last position moves the rule to the end.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"RoleMappingRule","description":"Operations about identity-provider role-mapping rules"}],"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":{"roleMappingRulePublicDto.generated":{"type":"object","properties":{"id":{"type":"string"},"expression":{"type":"string"},"role":{"type":"string"},"type":{"type":"string","enum":["instance","project"]},"order":{"type":"integer"},"projectIds":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","expression","role","type","order","projectIds","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."},"unsupportedMediaType":{"description":"Unsupported media type."}}},"paths":{"/role-mapping-rules/{roleMappingRuleId}/move":{"post":{"operationId":"moveRoleMappingRule","tags":["RoleMappingRule"],"summary":"Move a role-mapping rule","description":"Changes a rule's position in the evaluation order for its type. `targetIndex` is the desired 0-based position within the rule's own `type` sequence; a value beyond the last position moves the rule to the end.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the role mapping rule.","name":"roleMappingRuleId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targetIndex":{"type":"integer","minimum":0}},"required":["targetIndex"]}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/roleMappingRulePublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"415":{"$ref":"#/components/responses/unsupportedMediaType"}}}}}}
```

## Delete a role-mapping rule

> Deletes a role-mapping rule. The remaining rules of the same type close the gap, so their \`order\` values stay a contiguous sequence starting at 0.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"RoleMappingRule","description":"Operations about identity-provider role-mapping rules"}],"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":{"roleMappingRulePublicDto.generated":{"type":"object","properties":{"id":{"type":"string"},"expression":{"type":"string"},"role":{"type":"string"},"type":{"type":"string","enum":["instance","project"]},"order":{"type":"integer"},"projectIds":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","expression","role","type","order","projectIds","createdAt","updatedAt"]}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/role-mapping-rules/{roleMappingRuleId}":{"delete":{"operationId":"deleteRoleMappingRule","tags":["RoleMappingRule"],"summary":"Delete a role-mapping rule","description":"Deletes a role-mapping rule. The remaining rules of the same type close the gap, so their `order` values stay a contiguous sequence starting at 0.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the role mapping rule.","name":"roleMappingRuleId","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/roleMappingRulePublicDto.generated"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Update a role-mapping rule

> Updates a rule's claim expression, role, and/or project assignments. A rule's type cannot be changed once created, so \`type\` isn't accepted here, and reordering is handled by the move endpoint.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"RoleMappingRule","description":"Operations about identity-provider role-mapping rules"}],"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":{"roleMappingRulePublicDto.generated":{"type":"object","properties":{"id":{"type":"string"},"expression":{"type":"string"},"role":{"type":"string"},"type":{"type":"string","enum":["instance","project"]},"order":{"type":"integer"},"projectIds":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","expression","role","type","order","projectIds","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."},"unsupportedMediaType":{"description":"Unsupported media type."}}},"paths":{"/role-mapping-rules/{roleMappingRuleId}":{"patch":{"operationId":"updateRoleMappingRule","tags":["RoleMappingRule"],"summary":"Update a role-mapping rule","description":"Updates a rule's claim expression, role, and/or project assignments. A rule's type cannot be changed once created, so `type` isn't accepted here, and reordering is handled by the move endpoint.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the role mapping rule.","name":"roleMappingRuleId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expression":{"type":"string","minLength":1},"role":{"type":"string","minLength":1,"maxLength":128},"projectIds":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/roleMappingRulePublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"415":{"$ref":"#/components/responses/unsupportedMediaType"}}}}}}
```