Mobile App — Users

Management endpoints for mobile app users — the per-workspace staff/operator accounts that pair devices to the in-store mobile app. These endpoints are used by the web dashboard to create users, send pairing codes, and manage active device sessions.

Auth: All endpoints on this page require a Bearer token belonging to a member of the target workspace (createWorkspaceGuard, path-sourced workspaceId). They are distinct from the mobile-app session endpoints in Config & Runtime and Authentication, which use the X-Mobile-Token header.

A mobile app user moves through statuses: pending → paired (after a successful pairing-code exchange) / active, and may be suspended. Users may be created standalone or linked to an existing Directus workspace user (linked_user_id).

SDK methods live on wh.mobileAppUsers (MobileAppUsersService).

---

List mobile app users

GET /wallethero-api/workspace/:workspaceId/mobile-app-users

Lists mobile app users for a workspace, newest first, with a total count in meta.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier

Query Parameters

Parameter	Type	Required	Default	Description
limit	number	No	50	Max items to return
offset	number	No	0	Pagination offset
search	string	No	—	Free-text search across user fields
status	string	No	—	Filter by status (pending | paired | active | suspended)

Example Request

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-users?limit=25&status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "id": "9d1b...",
      "workspace_id": "WORKSPACE_ID",
      "email": "[email protected]",
      "phone": null,
      "first_name": "Sam",
      "last_name": "Taylor",
      "status": "active",
      "linked_user_id": null,
      "paired_at": "2026-06-10T08:30:00.000Z",
      "last_login": "2026-06-16T09:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "limit": 25, "offset": 0 }
}

SDK

const res = await wh.mobileAppUsers.list(workspaceId, { limit: 25, status: "active" });

---

Create a mobile app user

POST /wallethero-api/workspace/:workspaceId/mobile-app-users

Creates a standalone mobile app user in the workspace with status pending. At least one of email or phone is required. Rejects duplicates that share an email or phone with an existing user in the same workspace.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier

Request Body

Field	Type	Required	Description
email	string (email)	Conditional	Required if phone is omitted
phone	string	Conditional	Required if email is omitted
first_name	string	No	First name
last_name	string	No	Last name
metadata	object	No	Arbitrary metadata

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "first_name": "Sam", "last_name": "Taylor" }'

Response (201)

{
  "data": {
    "id": "9d1b...",
    "workspace_id": "WORKSPACE_ID",
    "email": "[email protected]",
    "first_name": "Sam",
    "last_name": "Taylor",
    "status": "pending"
  }
}

SDK

const res = await wh.mobileAppUsers.create(workspaceId, {
  email: "[email protected]",
  first_name: "Sam",
  last_name: "Taylor",
});

---

Get a mobile app user

GET /wallethero-api/workspace/:workspaceId/mobile-app-users/:userId

Returns a single mobile app user scoped to the workspace.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier
userId	string (UUID)	Mobile app user identifier

Example Request

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-users/USER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{ "data": { "id": "USER_ID", "email": "[email protected]", "status": "active" } }

SDK

const res = await wh.mobileAppUsers.get(workspaceId, userId);

---

Update a mobile app user

PATCH /wallethero-api/workspace/:workspaceId/mobile-app-users/:userId

Updates a mobile app user's profile or status. All fields optional.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier
userId	string (UUID)	Mobile app user identifier

Request Body

Field	Type	Required	Description
email	string (email)	No	Email
phone	string	No	Phone
first_name	string	No	First name
last_name	string	No	Last name
status	string	No	One of pending | paired | active | suspended
metadata	object	No	Arbitrary metadata

Example Request

curl -X PATCH "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-users/USER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "suspended" }'

Response (200)

{ "data": { "id": "USER_ID", "status": "suspended" } }

SDK

const res = await wh.mobileAppUsers.update(workspaceId, userId, { status: "suspended" });
// Convenience: wh.mobileAppUsers.suspend(workspaceId, userId) / .activate(workspaceId, userId)

---

Delete a mobile app user

DELETE /wallethero-api/workspace/:workspaceId/mobile-app-users/:userId

Deletes the user and cascades: all of their sessions and pairing codes are removed first.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier
userId	string (UUID)	Mobile app user identifier

Example Request

curl -X DELETE "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-users/USER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{ "message": "Mobile app user deleted successfully" }

SDK

await wh.mobileAppUsers.delete(workspaceId, userId);

---

Send a pairing code

POST /wallethero-api/workspace/:workspaceId/mobile-app-users/:userId/send-pairing-code

Generates a fresh 6-digit pairing code for the user and (optionally) delivers it by SMS and/or email. Any pending codes for the user are revoked first. Rate-limited to a maximum number of codes per hour per user. When delivery_method is none, the plaintext code is returned in the response (for manual entry). The code is later exchanged at POST /mobile-app/auth/pair (see Authentication).

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier
userId	string (UUID)	Mobile app user identifier

Request Body

Field	Type	Required	Default	Description
delivery_method	string	No	email	One of sms | email | both | none. sms/both require the user to have a phone; email/both require an email.

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-users/USER_ID/send-pairing-code" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "delivery_method": "email" }'

Response (200)

{
  "message": "Pairing code sent",
  "pairing_code_id": "abc1...",
  "delivery_results": { "email": true },
  "expires_at": "2026-06-16T09:15:00.000Z"
}

With delivery_method: "none" the response additionally includes "code": "482915".

SDK

const res = await wh.mobileAppUsers.sendPairingCode(workspaceId, userId, { delivery_method: "email" });

---

List sessions for a user

GET /wallethero-api/workspace/:workspaceId/mobile-app-users/:userId/sessions

Lists the user's active (non-revoked) device sessions, most recently active first.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier
userId	string (UUID)	Mobile app user identifier

Example Request

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-users/USER_ID/sessions" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "id": "sess1...",
      "mobile_app_user_id": "USER_ID",
      "workspace_id": "WORKSPACE_ID",
      "device_name": "Front Desk iPad",
      "device_os": "iPadOS 17",
      "last_active_at": "2026-06-16T09:00:00.000Z",
      "expires_at": "2026-07-16T08:30:00.000Z"
    }
  ]
}

SDK

const res = await wh.mobileAppUsers.listSessions(workspaceId, userId);

---

Revoke a session

DELETE /wallethero-api/workspace/:workspaceId/mobile-app-users/:userId/sessions/:sessionId

Revokes a single device session (sets revoked_at). The session must belong to the given user and workspace.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier
userId	string (UUID)	Mobile app user identifier
sessionId	string (UUID)	Session identifier

Example Request

curl -X DELETE "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-users/USER_ID/sessions/SESSION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{ "message": "Session revoked successfully" }

SDK

await wh.mobileAppUsers.revokeSession(workspaceId, userId, sessionId);
// Convenience: wh.mobileAppUsers.revokeAllSessions(workspaceId, userId)

---

Create a user from an existing workspace user

POST /wallethero-api/workspace/:workspaceId/mobile-app-users/from-workspace-user

Creates a mobile app user linked (linked_user_id) to an existing Directus workspace member, copying their email and name. The target must be a member of the workspace and must not already be linked to a mobile app user. The new user starts as pending.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier

Request Body

Field	Type	Required	Description
workspace_user_id	string (UUID)	Yes	Directus user id of the workspace member to link

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-users/from-workspace-user" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "workspace_user_id": "DIRECTUS_USER_ID" }'

Response (201)

{
  "data": {
    "id": "9d1b...",
    "workspace_id": "WORKSPACE_ID",
    "email": "[email protected]",
    "linked_user_id": "DIRECTUS_USER_ID",
    "status": "pending"
  }
}

SDK

const res = await wh.mobileAppUsers.createFromWorkspaceUser(workspaceId, {
  workspace_user_id: "DIRECTUS_USER_ID",
});

---

List linkable workspace users

GET /wallethero-api/workspace/:workspaceId/linkable-users

Lists workspace members who are not yet linked to a mobile app user — i.e. candidates for from-workspace-user.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier

Example Request

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/linkable-users" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    { "id": "DIRECTUS_USER_ID", "email": "[email protected]", "first_name": "Alex", "last_name": "Lee" }
  ]
}

SDK

const res = await wh.mobileAppUsers.listLinkableUsers(workspaceId);