Ctrlk
StatusBack to peakcommerce.com
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

List all users for the tenant

get
/users
Required scopes
This endpoint requires the following scopes:
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Query parameters
limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20
offsetintegerOptional

Number of items to skip (default 0)

Default: 0
portalTypestringOptional

Filter by portal type (admin, customer, csr, partner)

Responses
200

Paginated list of users

application/json

A platform user (admin, customer, CSR, Sales, or partner)

idstring · uuidOptional
emailstring · emailOptional
portalTypestring · enumOptionalPossible values:
profileIdstring · uuidOptional
isActivebooleanOptional
externalAccountIdstring · nullableOptional
externalContactIdstring · nullableOptional
createdAtstring · date-timeOptional
get/users
GET /api/v1/users HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "name@gmail.com",
  "portalType": "admin",
  "profileId": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "externalAccountId": "text",
  "externalContactId": "text",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

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

POST /api/v1/users

Create a new user

post
/users
Required scopes
This endpoint requires the following scopes:
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Body
emailstring · emailRequired
passwordstring · min: 6Optional

Required for password (database) sign-in tenants. Auth0-managed tenants must OMIT this — the user sets their own password via the email Auth0 sends; supplying one returns 400.

profileIdstring · uuidRequired
portalTypestringOptional
externalAccountIdstringOptional
externalContactIdstringOptional
isActivebooleanOptional
Responses
201

User created

application/json

A platform user (admin, customer, CSR, Sales, or partner)

idstring · uuidOptional
emailstring · emailOptional
portalTypestring · enumOptionalPossible values:
profileIdstring · uuidOptional
isActivebooleanOptional
externalAccountIdstring · nullableOptional
externalContactIdstring · nullableOptional
createdAtstring · date-timeOptional
post/users
POST /api/v1/users HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 185

{
  "email": "name@gmail.com",
  "password": "text",
  "profileId": "123e4567-e89b-12d3-a456-426614174000",
  "portalType": "text",
  "externalAccountId": "text",
  "externalContactId": "text",
  "isActive": true
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "name@gmail.com",
  "portalType": "admin",
  "profileId": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "externalAccountId": "text",
  "externalContactId": "text",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

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}

Delete a user

delete
/users/{id}
Required scopes
This endpoint requires the following scopes:
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters
idstringRequired
Responses
204

User deleted

No content
delete/users/{id}
DELETE /api/v1/users/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

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}

Get user details

get
/users/{id}
Required scopes
This endpoint requires the following scopes:
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters
idstringRequired
Responses
200

User details

application/json

A platform user (admin, customer, CSR, Sales, or partner)

idstring · uuidOptional
emailstring · emailOptional
portalTypestring · enumOptionalPossible values:
profileIdstring · uuidOptional
isActivebooleanOptional
externalAccountIdstring · nullableOptional
externalContactIdstring · nullableOptional
createdAtstring · date-timeOptional
get/users/{id}
GET /api/v1/users/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "name@gmail.com",
  "portalType": "admin",
  "profileId": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "externalAccountId": "text",
  "externalContactId": "text",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

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

PATCH /api/v1/users/{id}

Update a user

patch
/users/{id}
Required scopes
This endpoint requires the following scopes:
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters
idstringRequired
Body
emailstring · emailOptional
passwordstringOptional
profileIdstringOptional
portalTypestringOptional
isActivebooleanOptional
Responses
200

User updated

application/json

A platform user (admin, customer, CSR, Sales, or partner)

idstring · uuidOptional
emailstring · emailOptional
portalTypestring · enumOptionalPossible values:
profileIdstring · uuidOptional
isActivebooleanOptional
externalAccountIdstring · nullableOptional
externalContactIdstring · nullableOptional
createdAtstring · date-timeOptional
patch/users/{id}
PATCH /api/v1/users/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "email": "name@gmail.com",
  "password": "text",
  "profileId": "text",
  "portalType": "text",
  "isActive": true
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "name@gmail.com",
  "portalType": "admin",
  "profileId": "123e4567-e89b-12d3-a456-426614174000",
  "isActive": true,
  "externalAccountId": "text",
  "externalContactId": "text",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

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.

PreviousRoles
NextAccounts

Last updated

Was this helpful?