> 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/user.md).

# User

Operations about users

## Retrieve all users

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"User","description":"Operations about users"}],"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":{"/users":{"get":{"operationId":"getUsers","tags":["User"],"summary":"Retrieve all users","description":"Retrieve all users from your instance. Only available for the instance owner.","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"name":"includeRole","in":"query"},{"schema":{"type":"string"},"required":false,"name":"projectId","in":"query"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"email":{"type":"string","nullable":true,"format":"email"},"firstName":{"type":"string","nullable":true,"readOnly":true},"lastName":{"type":"string","nullable":true,"readOnly":true},"isPending":{"type":"boolean","description":"Whether the user finished setting up their account in response to the invitation (true) or not (false).","readOnly":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"mfaEnabled":{"type":"boolean","description":"Whether the user has multi-factor authentication (MFA/2FA) enabled.","readOnly":true},"role":{"type":"string","readOnly":true}},"required":["id","email","firstName","lastName","isPending","createdAt","updatedAt","mfaEnabled"]}},"nextCursor":{"type":"string","nullable":true,"description":"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."}},"required":["data","nextCursor"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"description":"The given `projectId` does not exist."}}}}}}
```

## Create multiple users

> Create one or more users.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"User","description":"Operations about users"}],"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"},"unsupportedMediaType":{"description":"Unsupported media type."}}},"paths":{"/users":{"post":{"operationId":"createUser","tags":["User"],"summary":"Create multiple users","description":"Create one or more users.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"anyOf":[{"type":"string","enum":["global:admin","global:member","global:chatUser"]},{"type":"string","minLength":1}],"default":"global:member"}},"required":["email"]}}}}},"responses":{"201":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"email":{"type":"string","format":"email"},"inviteAcceptUrl":{"type":"string","description":"Link the invited user can open to finish setting up the account. Present only when the instance does not send invite emails.","readOnly":true},"emailSent":{"type":"boolean","description":"Whether the invite email was sent to the user.","readOnly":true},"role":{"type":"string","readOnly":true}},"required":["id","email","emailSent","role"]},"error":{"type":"string","description":"The reason the invite failed for this user. Empty when the invite succeeded.","readOnly":true}},"required":["user"]}}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"415":{"$ref":"#/components/responses/unsupportedMediaType"}}}}}}
```

## Get user by ID/Email

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"User","description":"Operations about users"}],"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":{"/users/{userId}":{"get":{"operationId":"getUser","tags":["User"],"summary":"Get user by ID/Email","description":"Retrieve a user from your instance. Only available for the instance owner.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID or email of the user.","name":"userId","in":"path"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"name":"includeRole","in":"query"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"email":{"type":"string","nullable":true,"format":"email"},"firstName":{"type":"string","nullable":true,"readOnly":true},"lastName":{"type":"string","nullable":true,"readOnly":true},"isPending":{"type":"boolean","description":"Whether the user finished setting up their account in response to the invitation (true) or not (false).","readOnly":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"mfaEnabled":{"type":"boolean","description":"Whether the user has multi-factor authentication (MFA/2FA) enabled.","readOnly":true},"role":{"type":"string","readOnly":true}},"required":["id","email","firstName","lastName","isPending","createdAt","updatedAt","mfaEnabled"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"description":"No user with that ID or email."}}}}}}
```

## Delete user

> Delete a user from your instance.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"User","description":"Operations about users"}],"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":{"/users/{userId}":{"delete":{"operationId":"deleteUser","tags":["User"],"summary":"Delete user","description":"Delete a user from your instance.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the user.","name":"userId","in":"path"},{"schema":{"type":"string","description":"ID of the project to transfer the deleted user's workflows and credentials to. Omit to delete those resources instead of transferring them."},"required":false,"name":"transferId","in":"query"}],"responses":{"204":{"description":"Operation successful."},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Change a user's global role

> Change a user's global role

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"User","description":"Operations about users"}],"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."},"unsupportedMediaType":{"description":"Unsupported media type."}}},"paths":{"/users/{userId}/role":{"patch":{"operationId":"changeRole","tags":["User"],"summary":"Change a user's global role","description":"Change a user's global role","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the user.","name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newRoleName":{"anyOf":[{"type":"string","enum":["global:admin","global:member","global:chatUser"]},{"type":"string","minLength":1}]}},"required":["newRoleName"]}}}},"responses":{"204":{"description":"Operation successful."},"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"}}}}}}
```