> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/admin-api/admin-users.md).

# Users

Manage portal users within your tenant. Admin users (portalType `admin`) are protected: their privilege fields (`portalType`, `profileId`, `isActive`) cannot be changed via API key, and they cannot be deleted via API key. Use the admin portal UI to manage admin accounts. At least one active admin must exist at all times — any operation that would leave zero active admins is rejected with `403 LAST_ADMIN_PROTECTED`. Non-admin users cannot be promoted to admin via API key — see `PATCH /api/v1/users/{id}`.

## Endpoints

### `GET /api/v1/users`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/users" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

*Notes, examples, or caveats for `GET /users` go here.*

### `POST /api/v1/users`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/users" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

Admin users (`portalType: admin`) cannot be created via API key — this applies whether `portalType` is set explicitly in the request body or inherited from the assigned profile's role. Use the admin portal to create and manage admin accounts.

For organizations whose sign-in is managed by Auth0, creating a user also provisions a matching Auth0 identity in the background (database-connection populations only — federated users are linked automatically the first time they sign in via SSO). This provisioning is best-effort and never fails the create request; the identity link completes on the user's first sign-in if it could not be established immediately.

On Auth0-managed tenants, **do not send `password`** — Auth0 owns the credential. The new user automatically receives an email with a secure link to set their own password, and supplying a `password` returns `400`. On password (database) tenants, `password` is required as before.

### `DELETE /api/v1/users/{id}`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/users/{id}" method="delete" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

Admin users (`portalType: admin`) cannot be deleted via API key — use the admin portal. Returns `403 ADMIN_USER_IMMUTABLE`. If this user is the last active admin, `403 LAST_ADMIN_PROTECTED` is returned instead.

### `GET /api/v1/users/{id}`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/users/{id}" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

*Notes, examples, or caveats for `GET /users/{id}` go here.*

### `PATCH /api/v1/users/{id}`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/users/{id}" method="patch" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

The fields `portalType`, `profileId`, and `isActive` are privilege-bearing and cannot be changed on admin users (`portalType: admin`) via API key — returns `403 ADMIN_USER_IMMUTABLE`. Setting `isActive: false` when this is the last active admin returns `403 LAST_ADMIN_PROTECTED` regardless of other fields.

On Auth0-managed tenants, `password` cannot be set here (returns `400`) — Auth0 owns the credential. Use the password-reset flow in the admin portal to send the user a reset email instead.

API keys also cannot promote a non-admin user to admin — this applies whether `portalType: "admin"` is set explicitly in the body or inherited from the assigned profile's role (e.g. sending `profileId` that points to an admin-role profile without an explicit `portalType`). Such requests return `403 ADMIN_USER_PROMOTION_FORBIDDEN`. Use the admin portal to promote users to admin.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peakcommerce.com/developers/admin-api/admin-users.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.