Users

Server

Download schema

List users

GET

https://api.wocart.store

/api/users

X-API-Key (header)

Returns a paginated list of team members. Each user includes their scopes array (["*"] for admins).

List users › query Parameters

role

string · enum

Enum values:

admin

staff

status

string · enum

Enum values:

active

inactive

search

string

Search by name or email

limit

integer · max: 100

Default: 50

offset

integer | null · min: 0

Default: 0

List users › Responses

200

List of users

success

boolean · required

User[] · required

count

integer · required

Number of items returned

Create user

POST

https://api.wocart.store

/api/users

X-API-Key (header)

Creates a new team member. Admin only.

What happens:

A user account is created in the database with a secure temporary password
The password is hashed using scrypt (same algorithm as better-auth)
An API key is generated for programmatic access
Initial permission scopes are assigned (if role is staff)
A best-effort invite email is sent via Sendili when the store's email config exists and is enabled — the outcome is reported in emailSent/emailError, and creation never fails because of the email

Authentication:

The new user receives a temporary password (returned once in this response, and included in the invite email when it sends)
They can sign in using email + temporary password
They should change their password on first login for security

Note: scopes are ignored for admin users — admins always have ["*"]. The API key is never emailed.

Create user › Request Body

email

string · email · required

name

string · minLength: 1 · required

role

string · enum

Defaults to staff.

Enum values:

admin

staff

Default: staff

scopes

string[]

Initial permission scopes. Ignored if role is admin.

Default: []

language

string · enum

Language for the invite email. Defaults to en.

Enum values:

Create user › Responses

User created. The apiKey and tempPassword fields are returned only in this response — store them immediately.

success

boolean · required

User · required

Team member record with permission scopes

apiKey

string · required

The raw API key for the new user — returned once at creation. Use POST /{id}/api-key/rotate to issue a new key.

tempPassword

string · required

Temporary password for the new user — returned once at creation. Share this with the user securely. They should change it on first login.

emailSent

boolean · required

Whether the invite email was handed to Sendili. False when email sending is not configured or the send failed — check emailError.

emailError

string | null · required

message

string · required

POST/api/users

curl https://api.wocart.store/api/users \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "email": "staff@example.com",
  "name": "Ahmed Benali",
  "role": "staff",
  "scopes": [
    "orders:read",
    "customers:read"
  ],
  "language": "ar"
}'

Example Request Body

{
  "email": "staff@example.com",
  "name": "Ahmed Benali",
  "role": "staff",
  "scopes": [
    "orders:read",
    "customers:read"
  ],
  "language": "ar"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "a1b2c3d4e5f6a7b8a1b2c3d4e5f6a7b8",
    "name": "Ahmed Benali",
    "email": "staff@example.com",
    "emailVerified": true,
    "image": null,
    "role": "staff",
    "status": "active",
    "language": "en",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z",
    "scopes": [
      "orders:read",
      "customers:read"
    ]
  },
  "apiKey": "cod_a1b2c3d4e5f6...",
  "tempPassword": "a1b2c3d4e5f6g7h8i9j0",
  "emailSent": true,
  "emailError": null,
  "message": "User created. Share the tempPassword with the user — it will not be shown again."
}

json

application/json

Get user

GET

https://api.wocart.store

/api/users/{id}

X-API-Key (header)

Returns full user record including their scopes array.

Get user › path Parameters

id

string · required

User ID

Get user › Responses

200

User detail with scopes

success

boolean · required

User · required

Team member record with permission scopes

Update user

PATCH

https://api.wocart.store

/api/users/{id}

X-API-Key (header)

Partial update — only include fields you want to change. To change scopes, use POST /{id}/scopes and DELETE /{id}/scopes/{scope}. To change role only, prefer PATCH /{id}/role.

Update user › path Parameters

id

string · required

User ID

Update user › Request Body

email

string · email

name

string · minLength: 1

role

string · enum

Enum values:

admin

staff

status

string · enum

Enum values:

active

inactive

Update user › Responses

200

User updated

success

boolean · required

User · required

Team member record with permission scopes

message

string · required

PATCH/api/users/{id}

curl https://api.wocart.store/api/users/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "email": "test@example.com",
  "name": "name",
  "role": "admin",
  "status": "active"
}'

Example Request Body

{
  "email": "test@example.com",
  "name": "name",
  "role": "admin",
  "status": "active"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "a1b2c3d4e5f6a7b8a1b2c3d4e5f6a7b8",
    "name": "Ahmed Benali",
    "email": "staff@example.com",
    "emailVerified": true,
    "image": null,
    "role": "staff",
    "status": "active",
    "language": "en",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z",
    "scopes": [
      "orders:read",
      "customers:read"
    ]
  },
  "message": "Operation completed successfully"
}

json

application/json

Update user role

PATCH

https://api.wocart.store

/api/users/{id}/role

X-API-Key (header)

Dedicated endpoint for role-only changes. Changing to admin effectively grants ["*"] scope.

Update user role › path Parameters

id

string · required

User ID

Update user role › Request Body

role

string · enum · required

Enum values:

admin

staff

Update user role › Responses

200

Role updated

success

boolean · required

User · required

Team member record with permission scopes

message

string · required

Grant scope to user

POST

https://api.wocart.store

/api/users/{id}/scopes

X-API-Key (header)

Grants a single permission scope to the user. Returns the full updated user record.

Grant scope to user › path Parameters

id

string · required

User ID

Grant scope to user › Request Body

scope

string · minLength: 1 · required

Grant scope to user › Responses

Scope granted

success

boolean · required

User · required

Team member record with permission scopes

message

string · required

Revoke scope from user

DELETE

https://api.wocart.store

/api/users/{id}/scopes/{scope}

X-API-Key (header)

Removes a permission scope from the user. If the scope was not granted, the operation succeeds silently.

Revoke scope from user › path Parameters

id

string · required

User ID

scope

string · required

The scope to revoke

Revoke scope from user › Responses

200

Scope revoked. Returns full updated user record.

success

boolean · required

User · required

Team member record with permission scopes

message

string · required

Rotate API key

POST

https://api.wocart.store

/api/users/{id}/api-key/rotate

X-API-Key (header)

Generates a new API key for the user, invalidating the previous one. Admin only. The raw key is returned only once — store it securely.

Rotate API key › path Parameters

id

string · required

User ID

Rotate API key › Responses

200

New API key issued. The raw key is shown only in this response.

success

boolean · required

object · required

message

string · required

Events Activity Logs