> 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.com/api/v1/openapi.json>" path="/users" method="get" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

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

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

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/users" method="post" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/users/{id}" method="delete" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/users/{id}" method="get" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/users/{id}" method="patch" %}
<https://api.peakcommerce.com/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.