> 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":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"limit":{"name":"limit","in":"query","description":"The maximum number of items to return.","required":false,"schema":{"type":"number","default":100,"maximum":250}},"offset":{"name":"offset","in":"query","description":"The number of items to skip before starting to collect the result set.","required":false,"schema":{"type":"number","default":0,"minimum":0}},"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"}},"includeRole":{"name":"includeRole","in":"query","description":"Whether to include the user's role or not.","required":false,"schema":{"type":"boolean","default":false}}},"schemas":{"userList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/user"}},"nextCursor":{"type":"string","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.","nullable":true}}},"user":{"required":["email"],"type":"object","properties":{"id":{"type":"string","readOnly":true},"email":{"type":"string","format":"email"},"firstName":{"maxLength":32,"type":"string","description":"User's first name","readOnly":true},"lastName":{"maxLength":32,"type":"string","description":"User's last name","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","description":"Time the user was created.","format":"date-time","readOnly":true},"updatedAt":{"type":"string","description":"Last time the user was updated.","format":"date-time","readOnly":true},"role":{"type":"string","readOnly":true},"mfaEnabled":{"type":"boolean","description":"Whether the user has multi-factor authentication (MFA/2FA) enabled.","readOnly":true}}}},"responses":{"unauthorized":{"description":"Unauthorized"}}},"paths":{"/users":{"get":{"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/offset"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/includeRole"},{"name":"projectId","in":"query","required":false,"explode":false,"allowReserved":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/userList"}}}},"401":{"$ref":"#/components/responses/unauthorized"}}}}}}
```

## 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":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/users":{"post":{"tags":["User"],"summary":"Create multiple users","description":"Create one or more users.","requestBody":{"description":"Array of users to be created.","required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string"}},"required":["email"]}}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"inviteAcceptUrl":{"type":"string"},"emailSent":{"type":"boolean"}}},"error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"}}}}}}
```

## 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":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"userIdentifier":{"name":"id","in":"path","description":"The ID or email of the user.","required":true,"schema":{"type":"string","format":"identifier"}},"includeRole":{"name":"includeRole","in":"query","description":"Whether to include the user's role or not.","required":false,"schema":{"type":"boolean","default":false}}},"schemas":{"user":{"required":["email"],"type":"object","properties":{"id":{"type":"string","readOnly":true},"email":{"type":"string","format":"email"},"firstName":{"maxLength":32,"type":"string","description":"User's first name","readOnly":true},"lastName":{"maxLength":32,"type":"string","description":"User's last name","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","description":"Time the user was created.","format":"date-time","readOnly":true},"updatedAt":{"type":"string","description":"Last time the user was updated.","format":"date-time","readOnly":true},"role":{"type":"string","readOnly":true},"mfaEnabled":{"type":"boolean","description":"Whether the user has multi-factor authentication (MFA/2FA) enabled.","readOnly":true}}}},"responses":{"unauthorized":{"description":"Unauthorized"}}},"paths":{"/users/{id}":{"get":{"tags":["User"],"summary":"Get user by ID/Email","description":"Retrieve a user from your instance. Only available for the instance owner.","parameters":[{"$ref":"#/components/parameters/userIdentifier"},{"$ref":"#/components/parameters/includeRole"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"}}}},"401":{"$ref":"#/components/responses/unauthorized"}}}}}}
```

## Delete a 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":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"userIdentifier":{"name":"id","in":"path","description":"The ID or email of the user.","required":true,"schema":{"type":"string","format":"identifier"}}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/users/{id}":{"delete":{"tags":["User"],"summary":"Delete a user","description":"Delete a user from your instance.","parameters":[{"$ref":"#/components/parameters/userIdentifier"}],"responses":{"204":{"description":"Operation successful."},"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":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"userIdentifier":{"name":"id","in":"path","description":"The ID or email of the user.","required":true,"schema":{"type":"string","format":"identifier"}}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/users/{id}/role":{"patch":{"tags":["User"],"summary":"Change a user's global role","description":"Change a user's global role","parameters":[{"$ref":"#/components/parameters/userIdentifier"}],"requestBody":{"description":"New role for the user","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newRoleName":{"type":"string"}},"required":["newRoleName"]}}}},"responses":{"200":{"description":"Operation successful."},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```