User

Operations about users

Retrieve all users

get

/users

Retrieve all users from your instance. Only available for the instance owner.

Authorizations

X-N8N-API-KEYstringRequired

Query parameters

limitnumber · max: 250Optional

The maximum number of items to return.

Default: 100Example: 100

cursorstringOptional

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.

includeRolestring · enumOptionalDefault: falsePossible values:

projectIdstringOptional

Responses

200

Operation successful.

application/json

nextCursorstring · nullableRequired

Paginate through users by setting the cursor parameter to a nextCursor attribute returned by a previous request. Default value fetches the first page of the collection.

Example: MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The given projectId does not exist.

get/users

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

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "[e-mail]",
      "firstName": "john",
      "lastName": "Doe",
      "isPending": true,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "mfaEnabled": false,
      "role": "global:owner"
    }
  ],
  "nextCursor": "MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA"
}

Create multiple users

post

/users

Create one or more users.

Authorizations

X-N8N-API-KEYstringRequired

Bodyobject[]

emailstring · emailRequired

roleany ofOptionalDefault: global:member

string · enumOptionalPossible values:

or

string · min: 1Optional

Responses

201

Operation successful.

application/json

errorstringRead-onlyOptional

The reason the invite failed for this user. Empty when the invite succeeded.

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

415

Unsupported media type.

post/users

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

[
  {
    "email": "[e-mail]",
    "role": "global:member"
  }
]

[
  {
    "user": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "[e-mail]",
      "inviteAcceptUrl": "text",
      "emailSent": true,
      "role": "global:member"
    },
    "error": "text"
  }
]

Get user by ID/Email

get

/users/{userId}

Retrieve a user from your instance. Only available for the instance owner.

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

userIdstringRequired

The ID or email of the user.

Query parameters

includeRolestring · enumOptionalDefault: falsePossible values:

Responses

200

Operation successful.

application/json

idstringRead-onlyRequiredExample: 123e4567-e89b-12d3-a456-426614174000

emailstring · email · nullableRequiredExample: [e-mail]

firstNamestring · nullableRead-onlyRequiredExample: john

lastNamestring · nullableRead-onlyRequiredExample: Doe

isPendingbooleanRead-onlyRequired

Whether the user finished setting up their account in response to the invitation (true) or not (false).

createdAtstring · date-timeRead-onlyRequired

updatedAtstring · date-timeRead-onlyRequired

mfaEnabledbooleanRead-onlyRequired

Whether the user has multi-factor authentication (MFA/2FA) enabled.

Example: false

rolestringRead-onlyOptionalExample: global:owner

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

No user with that ID or email.

get/users/{userId}

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "[e-mail]",
  "firstName": "john",
  "lastName": "Doe",
  "isPending": true,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "mfaEnabled": false,
  "role": "global:owner"
}

Delete user

delete

/users/{userId}

Delete a user from your instance.

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

userIdstringRequired

The ID of the user.

Query parameters

transferIdstringOptional

ID of the project to transfer the deleted user's workflows and credentials to. Omit to delete those resources instead of transferring them.

Responses

204

Operation successful.

No content

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

delete/users/{userId}

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

No content

Change a user's global role

patch

/users/{userId}/role

Change a user's global role

Authorizations

X-N8N-API-KEYstringRequired

Path parameters

userIdstringRequired

The ID of the user.

Body

newRoleNameany ofRequired

string · enumOptionalPossible values:

or

string · min: 1Optional

Responses

204

Operation successful.

No content

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

415

Unsupported media type.

patch/users/{userId}/role

PATCH /api/v1/users/{userId}/role HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "newRoleName": "global:admin"
}

No content