Role Mapping Rule
Operations about identity-provider 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.
The maximum number of items to return.
100Example: 100Paginate 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.
Operation successful.
The request is invalid or provides malformed data.
Unauthorized
Forbidden
GET /api/v1/role-mapping-rules HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*
{
"data": [
{
"id": "text",
"expression": "text",
"role": "text",
"type": "instance",
"order": 1,
"projectIds": [
"text"
],
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
],
"nextCursor": "text"
}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.
Operation successful.
The request is invalid or provides malformed data.
Unauthorized
Forbidden
The specified resource was not found.
Unsupported media type.
POST /api/v1/role-mapping-rules HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 85
{
"expression": "text",
"role": "text",
"type": "instance",
"order": 1,
"projectIds": [
"text"
]
}{
"id": "text",
"expression": "text",
"role": "text",
"type": "instance",
"order": 1,
"projectIds": [
"text"
],
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}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.
The ID of the role mapping rule.
Operation successful.
The request is invalid or provides malformed data.
Unauthorized
Forbidden
The specified resource was not found.
Unsupported media type.
POST /api/v1/role-mapping-rules/{roleMappingRuleId}/move HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"targetIndex": 1
}{
"id": "text",
"expression": "text",
"role": "text",
"type": "instance",
"order": 1,
"projectIds": [
"text"
],
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}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.
The ID of the role mapping rule.
Operation successful.
Unauthorized
Forbidden
The specified resource was not found.
DELETE /api/v1/role-mapping-rules/{roleMappingRuleId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*
{
"id": "text",
"expression": "text",
"role": "text",
"type": "instance",
"order": 1,
"projectIds": [
"text"
],
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}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.
The ID of the role mapping rule.
Operation successful.
The request is invalid or provides malformed data.
Unauthorized
Forbidden
The specified resource was not found.
Unsupported media type.
PATCH /api/v1/role-mapping-rules/{roleMappingRuleId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 57
{
"expression": "text",
"role": "text",
"projectIds": [
"text"
]
}{
"id": "text",
"expression": "text",
"role": "text",
"type": "instance",
"order": 1,
"projectIds": [
"text"
],
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}Last updated
Was this helpful?