Merchant Users#

Manage merchant user accounts (the merchant's team) and their access.

Team members are user accounts in the auth service, managed under /api/v1/users. A member belongs to a merchant through its merchantId (or an additional merchant link). All endpoints require Authorization: Bearer <JWT>; the tenant comes from the token.

Tenant admins can manage users of any merchant in the tenant.
Merchant users only see and manage members of their own (active) merchant, and can only invite into a role below their own (an Admin invites Managers, Staff and custom roles, never another Admin or an Owner).
A merchant can have only one Merchant Owner.

Create User#

POST/api/v1/users

Creates a team member and sends an invitation email with a password-setup link. The member stays Pending until the link is used.

Create Userbash

curl -X POST https://uat.auxcore.net/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "TempPassw0rd!",
    "firstName": "Sam",
    "lastName": "Rivera",
    "role": "merchant_staff",
    "merchantId": "8f3c2a1e-5b7d-4e9a-9c1f-2d6e8a4b7c30",
    "branchIds": ["3d1f8e2a-7c4b-4a9e-8f2d-1b6c9e0a5d47"],
    "sendInvite": true
  }'

Request Body:

Field	Type	Required	Description
`email`	email	Yes	Must be a valid email address
`password`	string	Yes	Initial password (the member normally sets their own through the invite link)
`merchantId`	uuid	No	Merchant the member joins. Required to add someone to a merchant team.
`role`	string	No	Role code, e.g. `merchant_owner`, `merchant_admin`, `merchant_staff`, or a custom role. Default `user`.
`firstName`, `lastName`	string	No	`fullName` is composed from these
`fullName`	string	No	Used when first/last name are not sent
`jobTitle`	string	No
`phone`	string	No	`phoneNumber` is accepted as an alias
`branchIds`	uuid[]	No	Locations the member is assigned to. Empty or omitted means all locations.
`mfaRequired`	boolean	No	Require MFA at login
`sendInvite`	boolean	No	Default `true`. `false` creates the Pending member without emailing; send the invite later.
`permissionOverrides`	object	No	`{ "granted": string[], "revoked": string[] }` — per-member changes on top of the role. Needs `users.manage`; not allowed for a Merchant Owner. See User Permissions.

Response (201 Created):

Create Userjson

{
  "success": true,
  "data": {
    "id": "c2b7e4a9-1d3f-4e8b-9a6c-5f0d2e7b8a13",
    "email": "user@example.com",
    "fullName": "Sam Rivera",
    "role": "merchant_staff",
    "merchantId": "8f3c2a1e-5b7d-4e9a-9c1f-2d6e8a4b7c30",
    "isActive": true,
    "mfaEnabled": false,
    "invitedAt": "2026-01-28T12:00:00.000Z",
    "inviteAcceptedAt": null
  }
}

If the email already belongs to a merchant-side account in this tenant, that account is linked to the merchant instead and the response is 200 OK with "message": "User linked to merchant successfully".

Errors: 400 VALIDATION_ERROR (missing email/password, invalid email, User with this email already exists when no merchantId is sent, User already exists for this merchant, platform account email), 403 FORBIDDEN (role you may not grant, second Owner), 409 EMAIL_IN_USE.

List Users#

GET/api/v1/users

Requires users.view.

Query	Description
`merchantId`	Admins only: limit to one merchant's team (primary members and linked members)
`scope`	Admins only: `platform` returns internal staff instead of merchant users

Merchant users always get their own merchant's team, regardless of the query.

Response:

List Usersjson

{
  "success": true,
  "data": [
    {
      "id": "c2b7e4a9-1d3f-4e8b-9a6c-5f0d2e7b8a13",
      "email": "user@example.com",
      "fullName": "Sam Rivera",
      "role": "merchant_staff",
      "merchantId": "8f3c2a1e-5b7d-4e9a-9c1f-2d6e8a4b7c30",
      "isActive": true
    }
  ]
}

List a Merchant's Team#

GET/api/v1/merchants/:merchantId/users

Returns the same team list for one merchant, served by the merchant service. Items carry a shorter projection: id, email, fullName, role, merchantId, isActive, mfaEnabled, createdAt, updatedAt.

Get User#

GET/api/v1/users/:userId

Requires users.view. Returns 404 if the user does not exist in the tenant.

Update User#

PUT/api/v1/users/:userId

All fields are optional: firstName, lastName, fullName, jobTitle, phone, email, role, isActive, mfaEnabled, mfaRequired, branchIds, permissionOverrides.

Update Userbash

curl -X PUT https://uat.auxcore.net/api/v1/users/c2b7e4a9-1d3f-4e8b-9a6c-5f0d2e7b8a13 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "merchant_admin"}'

Users can edit their own profile but cannot change their own role or permissions.
Only admins, or merchant admins for members of their own merchant, can change role, isActive, branchIds and mfaRequired.
Merchant users cannot assign platform admin roles.

Activate / Deactivate User#

PATCH/api/v1/users/:userId/status

Activate / Deactivate Userjson

{ "isActive": false }

Same rules as Update User.

Resend Invitation#

POST/api/v1/users/:userId/send-invite

Emails a fresh password-setup link. POST /api/v1/users/:userId/invite-link returns the link instead of emailing it.

Delete User#

DELETE/api/v1/users/:userId

Soft-deletes the user. When a merchant user removes a member who also belongs to other merchants, the member is only removed from the caller's merchant ("message": "User removed from this merchant successfully"); the account itself stays. You cannot delete your own account or the protected Super Admin, and only a tenant admin can remove a merchant's Owner (transfer ownership first). Merchant admins cannot remove a peer of the same tier.

Need help? Contact support@auxcore.net