Role

Operations about roles

Retrieve all roles

get

/roles

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

Authorizations

X-N8N-API-KEYstringRequired

Query parameters

withUsageCountstring · enumOptionalDefault: falsePossible values:

Responses

200

Operation successful.

application/json

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

get/roles

GET /api/v1/roles HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "global": [
    {
      "slug": "text",
      "displayName": "text",
      "description": "text",
      "systemRole": true,
      "roleType": "global",
      "scopes": [
        "text"
      ],
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "licensed": true,
      "usedByUsers": 1,
      "usedByProjects": 1
    }
  ],
  "project": [
    {
      "slug": "text",
      "displayName": "text",
      "description": "text",
      "systemRole": true,
      "roleType": "project",
      "scopes": [
        "text"
      ],
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "licensed": true,
      "usedByUsers": 1,
      "usedByProjects": 1
    }
  ]
}

Create a custom role

post

/roles

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

Authorizations

X-N8N-API-KEYstringRequired

Body

displayNamestring · min: 2 · max: 100Required

descriptionstring · max: 500Optional

roleTypestring · enumRequiredPossible values:

scopesstring[]Required

Responses

201

Operation successful.

application/json

slugstringRequired

displayNamestringRequired

descriptionstring · nullableRequired

systemRolebooleanRequired

roleTypestring · enumRequiredPossible values:

scopesstring[]Required

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

415

Unsupported media type.

post/roles

POST /api/v1/roles HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "displayName": "text",
  "description": "text",
  "roleType": "project",
  "scopes": [
    "text"
  ]
}

{
  "slug": "text",
  "displayName": "text",
  "description": "text",
  "systemRole": true,
  "roleType": "project",
  "scopes": [
    "text"
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Retrieve a role

get

/roles/{roleSlug}

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

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

roleSlugstringRequired

The slug of the role.

Query parameters

withUsageCountstring · enumOptionalDefault: falsePossible values:

Responses

200

Operation successful.

application/json

slugstringRequired

displayNamestringRequired

descriptionstring · nullableRequired

systemRolebooleanRequired

roleTypestring · enumRequiredPossible values:

scopesstring[]Required

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

licensedbooleanRequired

usedByUsersnumberOptional

usedByProjectsnumberOptional

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

get/roles/{roleSlug}

GET /api/v1/roles/{roleSlug} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "slug": "text",
  "displayName": "text",
  "description": "text",
  "systemRole": true,
  "roleType": "project",
  "scopes": [
    "text"
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "licensed": true,
  "usedByUsers": 1,
  "usedByProjects": 1
}

Update a custom role

put

/roles/{roleSlug}

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

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

roleSlugstringRequired

The slug of the role.

Body

displayNamestring · min: 2 · max: 100Required

descriptionstring · max: 500 · nullableRequired

scopesstring[]Required

Responses

200

Operation successful.

application/json

slugstringRequired

displayNamestringRequired

descriptionstring · nullableRequired

systemRolebooleanRequired

roleTypestring · enumRequiredPossible values:

scopesstring[]Required

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

415

Unsupported media type.

put/roles/{roleSlug}

PUT /api/v1/roles/{roleSlug} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "displayName": "text",
  "description": "text",
  "scopes": [
    "text"
  ]
}

{
  "slug": "text",
  "displayName": "text",
  "description": "text",
  "systemRole": true,
  "roleType": "project",
  "scopes": [
    "text"
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Delete a custom role

delete

/roles/{roleSlug}

Deletes a custom role. System roles cannot be deleted. A role with users assigned cannot be deleted unless reassignRoleSlug is set to move those users to another role first.

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

roleSlugstringRequired

The slug of the role.

Query parameters

reassignRoleSlugany ofOptional

string · enumOptionalPossible values:

or

string · min: 1Optional

Responses

200

Operation successful.

application/json

slugstringRequired

displayNamestringRequired

descriptionstring · nullableRequired

systemRolebooleanRequired

roleTypestring · enumRequiredPossible values:

scopesstring[]Required

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

delete/roles/{roleSlug}

DELETE /api/v1/roles/{roleSlug} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "slug": "text",
  "displayName": "text",
  "description": "text",
  "systemRole": true,
  "roleType": "project",
  "scopes": [
    "text"
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}