Skip to main content
API docs by Redocly

Wallboard API - User & Team Management (2.0)

API Support: [email protected]

User and team management endpoints for the Wallboard digital signage platform.

Overview

Users are individuals who can log in to the Wallboard admin interface. Teams (user groups) provide granular access control by grouping resources and users.

Key Concepts

Concept Description
User Individual account with role-based permissions
Team Group for managing resource access (also called "user group")
Role Permission level determining what actions a user can perform
Editor Level Content editor capability tier
UI Profile Customized interface configuration

User Roles (Hierarchy)

Role Description
ADMIN Full system access across all tenants
OWNER Full customer access, can manage users and teams
TECHNICIAN Can configure devices, datasources, integrations
APPROVER Can approve content before publishing
EDITOR Can create and edit content
VIEWER Read-only access to assigned resources
DEVICE_USER Device-only account for display authentication

Editor Levels

Level Description
BASIC Simple editing with limited widget access
ADVANCED Standard editing with most widgets
PROFESSIONAL Full editor access with all features

Team-Based Access Control

Teams enable fine-grained access:

  • Assign users to teams
  • Assign resources (devices, content, files, etc.) to teams
  • Users only see resources from their teams
  • Resources can be readOnly for a team (view but not modify)

Filtering

Use WBQL in the search parameter. Key fields:

For Users:

Filter Type Field Example
Role role search=role=EDITOR
Email email search=email:john
Name name search=name:John
Active active search=active=true

For Teams:

Filter Type Field Example
Name name search=name:marketing

See Getting Started for full WBQL syntax.

UI profile management is documented in the Administration API.

user

User management

List users (V2)

Retrieve a paginated list of users with support for field selection.

Minimum role: DEVICE_USER

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

page
integer >= 0
Default: 0

Page index (0-based)

size
integer >= 1
Default: 20

Requested page size; server limits and endpoint overrides apply.

sort
string
Example: sort=name,asc

Sort expression. Format: field,direction

  • Directions: asc, desc
  • Multiple sorts: sort=name,asc&sort=lastActivity,desc
  • Nested fields: sort=content.name,asc
search
string

WBQL filter expression. Operators: : (contains), = (equals), ≠, ∉, ^ (starts with), >, ≥, <, ≤, ∈ (in set). Logic: , (AND), | (OR). Special: NULL, !NULL. Example: name:lobby,deviceStatus=ONLINE

select
string

Field projection. * = all primitives, field,field = specific, relation(fields) = nested. Example: select=*,customer(id,name)

Responses

Response samples

Content type
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "size": 0,
  • "content": [
    ]
}

Get current user

Get the authenticated user's profile. Returns role, customerId, and customer details.

Minimum role: DEVICE_USER

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "email": "[email protected]",
  • "name": "string",
  • "language": "string",
  • "address": "string",
  • "comment": "string",
  • "iconUrl": "string",
  • "lastLogin": 0,
  • "createdDate": 0,
  • "termsOfServiceAcceptDate": 0,
  • "logins": 0,
  • "presenceTime": 0,
  • "lastActivity": 0,
  • "editorLevel": "BASIC",
  • "role": "DEVICE_USER",
  • "readOnly": true,
  • "forceToSet2FA": true,
  • "authProvider": "LOCAL",
  • "use2FA": true,
  • "restricted": true,
  • "hiddenUIElementRules": { },
  • "ssoLoginEnabled": true,
  • "usernamePasswordLoginEnabled": true,
  • "magicCodeLoginEnabled": true,
  • "hasProfilePicture": true,
  • "profilePictureApiPath": "string",
  • "microsoftSsoEnabled": true,
  • "pinCodePresent": true,
  • "regionalFormatSettings": { },
  • "ownerCanAccessNetworkMember": true,
  • "userInterfaceProfileId": 0,
  • "customerId": 0,
  • "location": {
    },
  • "trustedAdmin": true,
  • "oauthPasswordFlowEnabled": true,
  • "active": true,
  • "customer": {
    },
  • "userInterfaceProfile": {
    },
  • "restrictionMessage": "string",
  • "userMetadata": null
}

Create user

Create a new user account.

Minimum role: OWNER

⚠️ Protected: Requires g-recaptcha-response header (if CAPTCHA enabled) and/or x-totp header (if caller has 2FA).

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

teamIds
string
Example: teamIds=000c08d294df48efb1b0f5aa754d7ef9:true,00a22e86602c4a88914614aa9516a481:false

Team assignments for a newly created resource. Comma-separated teamId:readOnly pairs.

Request Body schema: application/json
required
email
required
string <email>
name
required
string
password
string <password>

Initial password (required unless SSO-only)

language
string
Default: "en"
address
string
comment
string
iconUrl
string
role
required
string (UserRole)
Enum: "DEVICE_USER" "VIEWER" "EDITOR" "APPROVER" "TECHNICIAN" "OWNER" "ADMIN"

User permission level (hierarchy from lowest to highest)

editorLevel
string (EditorLevel)
Enum: "BASIC" "ADVANCED" "PROFESSIONAL"

Content editor capability tier

readOnly
boolean
Default: false
forceToSet2FA
boolean
Default: false
restricted
boolean
Default: false
hiddenUIElementRules
object
userMetadata
object
ssoLoginEnabled
boolean
Default: true
usernamePasswordLoginEnabled
boolean
Default: true
magicCodeLoginEnabled
boolean
Default: true
regionalFormatSettings
object
ownerCanAccessNetworkMember
boolean
userInterfaceProfileId
integer <int64>
trustedAdmin
boolean
Default: true
oauthPasswordFlowEnabled
boolean
Default: false
restrictionMessage
string

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "name": "string",
  • "password": "pa$$word",
  • "language": "en",
  • "address": "string",
  • "comment": "string",
  • "iconUrl": "string",
  • "role": "DEVICE_USER",
  • "editorLevel": "BASIC",
  • "readOnly": false,
  • "forceToSet2FA": false,
  • "restricted": false,
  • "hiddenUIElementRules": { },
  • "userMetadata": { },
  • "ssoLoginEnabled": true,
  • "usernamePasswordLoginEnabled": true,
  • "magicCodeLoginEnabled": true,
  • "regionalFormatSettings": { },
  • "ownerCanAccessNetworkMember": true,
  • "userInterfaceProfileId": 0,
  • "trustedAdmin": true,
  • "oauthPasswordFlowEnabled": false,
  • "restrictionMessage": "string"
}

Response samples

Content type
application/json
{
  • "email": "[email protected]",
  • "name": "string",
  • "language": "string",
  • "address": "string",
  • "comment": "string",
  • "iconUrl": "string",
  • "lastLogin": 0,
  • "createdDate": 0,
  • "termsOfServiceAcceptDate": 0,
  • "logins": 0,
  • "presenceTime": 0,
  • "lastActivity": 0,
  • "editorLevel": "BASIC",
  • "role": "DEVICE_USER",
  • "readOnly": true,
  • "forceToSet2FA": true,
  • "authProvider": "LOCAL",
  • "use2FA": true,
  • "restricted": true,
  • "hiddenUIElementRules": { },
  • "ssoLoginEnabled": true,
  • "usernamePasswordLoginEnabled": true,
  • "magicCodeLoginEnabled": true,
  • "hasProfilePicture": true,
  • "profilePictureApiPath": "string",
  • "microsoftSsoEnabled": true,
  • "pinCodePresent": true,
  • "regionalFormatSettings": { },
  • "ownerCanAccessNetworkMember": true,
  • "userInterfaceProfileId": 0,
  • "customerId": 0,
  • "location": {
    },
  • "trustedAdmin": true,
  • "oauthPasswordFlowEnabled": true,
  • "active": true,
  • "customer": {
    },
  • "userInterfaceProfile": {
    },
  • "restrictionMessage": "string",
  • "userMetadata": null
}

Update user

Update an existing user.

Minimum role: DEVICE_USER (can update own profile, OWNER required for others)

⚠️ Protected: Requires g-recaptcha-response header (if CAPTCHA enabled) and/or x-totp header (if caller has 2FA).

Authorizations:
bearer
query Parameters
email
required
string <email>

Email of the user to update

Request Body schema: application/json
required
email
string <email>

New email address (to change email)

name
string
password
string <password>

New password

language
string
address
string
comment
string
iconUrl
string
role
string (UserRole)
Enum: "DEVICE_USER" "VIEWER" "EDITOR" "APPROVER" "TECHNICIAN" "OWNER" "ADMIN"

User permission level (hierarchy from lowest to highest)

editorLevel
string (EditorLevel)
Enum: "BASIC" "ADVANCED" "PROFESSIONAL"

Content editor capability tier

readOnly
boolean
forceToSet2FA
boolean
use2FA
boolean
restricted
boolean
hiddenUIElementRules
object
userMetadata
object
ssoLoginEnabled
boolean
usernamePasswordLoginEnabled
boolean
magicCodeLoginEnabled
boolean
regionalFormatSettings
object
ownerCanAccessNetworkMember
boolean
userInterfaceProfileId
integer <int64>
resetUserInterfaceProfile
boolean

Remove UI profile assignment

trustedAdmin
boolean
oauthPasswordFlowEnabled
boolean
resetRegionalFormatSettings
boolean
resetRestrictionMessage
boolean
restrictionMessage
string

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "name": "string",
  • "password": "pa$$word",
  • "language": "string",
  • "address": "string",
  • "comment": "string",
  • "iconUrl": "string",
  • "role": "DEVICE_USER",
  • "editorLevel": "BASIC",
  • "readOnly": true,
  • "forceToSet2FA": true,
  • "use2FA": true,
  • "restricted": true,
  • "hiddenUIElementRules": { },
  • "userMetadata": { },
  • "ssoLoginEnabled": true,
  • "usernamePasswordLoginEnabled": true,
  • "magicCodeLoginEnabled": true,
  • "regionalFormatSettings": { },
  • "ownerCanAccessNetworkMember": true,
  • "userInterfaceProfileId": 0,
  • "resetUserInterfaceProfile": true,
  • "trustedAdmin": true,
  • "oauthPasswordFlowEnabled": true,
  • "resetRegionalFormatSettings": true,
  • "resetRestrictionMessage": true,
  • "restrictionMessage": "string"
}

Delete user

Delete a user account.

Minimum role: OWNER

⚠️ Protected: Requires g-recaptcha-response header (if CAPTCHA enabled) and/or x-totp header (if caller has 2FA).

Authorizations:
bearer
query Parameters
email
required
string <email>

Email of the user to delete

Responses

Delete own account

Delete the currently authenticated user's own account.

Minimum role: DEVICE_USER

⚠️ Protected: Requires g-recaptcha-response header (if CAPTCHA enabled) and/or x-totp header (if caller has 2FA).

Authorizations:
bearer

Responses

Change password

Change the current user's password.

Minimum role: DEVICE_USER

⚠️ Protected: Requires g-recaptcha-response header (if CAPTCHA enabled) and/or x-totp header (if caller has 2FA).

Authorizations:
bearer
query Parameters
oldPassword
required
string <password>
newPassword
required
string <password>
totp
string

TOTP code if 2FA is enabled

Responses

Set user PIN code

Set a PIN code for quick device authentication.

Minimum role: DEVICE_USER

Authorizations:
bearer
query Parameters
email
string <email>

Email of the user (optional, defaults to current user)

pinCode
string^\d{4,8}$

4-8 digit PIN code (null to clear)

Responses

Enable/disable 2FA

Enable or disable two-factor authentication for current user.

Minimum role: DEVICE_USER

⚠️ Protected: Requires g-recaptcha-response header (if CAPTCHA enabled).

Authorizations:
bearer
query Parameters
totp
required
string

Current TOTP code to verify

enable
required
boolean

Whether to enable or disable 2FA

Responses

Get TOTP secret for 2FA setup

Get or generate TOTP secret for setting up two-factor authentication.

Minimum role: DEVICE_USER

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "secret": "string"
}

Accept terms of service

Accept or decline the terms of service.

Minimum role: DEVICE_USER

Authorizations:
bearer
path Parameters
accepted
required
boolean

Responses

Get terms of service acceptance info

Get information about the user's terms of service acceptance status.

Minimum role: DEVICE_USER

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "userAcceptedTermsOfServiceDate": 0,
  • "termsOfServiceLastUpdatedDate": 0,
  • "userAcceptedLatestTermsOfService": true
}

Update user team assignments

Update which teams a user belongs to.

Minimum role: OWNER

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

email
required
string <email>

Email of the user to update

Request Body schema: application/json
required
Array of objects (DefaultTeamAssignmentParams)

Teams to assign the resource to

removeFromTeamIds
Array of strings

Team IDs to remove the resource from

Responses

Request samples

Content type
application/json
{
  • "assignToTeams": [
    ],
  • "removeFromTeamIds": [
    ]
}

Upload profile picture

Upload a new profile picture for the current user.

Minimum role: DEVICE_USER

Authorizations:
bearer
Request Body schema: multipart/form-data
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "picturePath": "string"
}

Delete profile picture

Delete the current user's profile picture.

Minimum role: DEVICE_USER

Authorizations:
bearer

Responses

Export users as CSV

Export user list as CSV file.

Minimum role: OWNER

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

search
string

WBQL filter expression. Operators: : (contains), = (equals), ≠, ∉, ^ (starts with), >, ≥, <, ≤, ∈ (in set). Logic: , (AND), | (OR). Special: NULL, !NULL. Example: name:lobby,deviceStatus=ONLINE

Responses

Send feedback

Submit feedback about the platform.

Minimum role: DEVICE_USER

Authorizations:
bearer
Request Body schema: application/json
required
message
required
string
messageType
string

Type of feedback (e.g., "bug", "feature", "question")

Array of objects (ImageAttachment)

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "messageType": "string",
  • "images": [
    ]
}

Send content request

Request custom content creation assistance.

Minimum role: DEVICE_USER

Authorizations:
bearer
Request Body schema: application/json
required
message
required
string
messageType
string
Array of objects (ImageAttachment)
contentName
string

Name for the requested content

startDate
string

Desired start date

endDate
string

Desired end date

targetScreenGroup
string

Target screen group for the content

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "messageType": "string",
  • "images": [
    ],
  • "contentName": "string",
  • "startDate": "string",
  • "endDate": "string",
  • "targetScreenGroup": "string"
}

Logout all sessions

Invalidate all refresh tokens for the current user, logging out all sessions.

Minimum role: DEVICE_USER

Authorizations:
bearer

Responses

Get Microsoft SSO connect URL

Get URL to connect Microsoft account for SSO.

Minimum role: DEVICE_USER

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "url": "string"
}

Disconnect Microsoft SSO

Disconnect Microsoft account from SSO.

Minimum role: DEVICE_USER

Authorizations:
bearer

Responses

Check user access and role

Check if current user has access to a customer and optionally verify role.

Minimum role: DEVICE_USER

Authorizations:
bearer
query Parameters
customerId
required
integer
role
string (UserRole)
Enum: "DEVICE_USER" "VIEWER" "EDITOR" "APPROVER" "TECHNICIAN" "OWNER" "ADMIN"

Minimum role to check for

Responses

team

Team (user group) management

List teams

Retrieve a paginated list of teams.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

page
integer >= 0
Default: 0

Page index (0-based)

size
integer >= 1
Default: 20

Requested page size; server limits and endpoint overrides apply.

sort
string
Example: sort=name,asc

Sort expression. Format: field,direction

  • Directions: asc, desc
  • Multiple sorts: sort=name,asc&sort=lastActivity,desc
  • Nested fields: sort=content.name,asc
search
string

WBQL filter expression. Operators: : (contains), = (equals), ≠, ∉, ^ (starts with), >, ≥, <, ≤, ∈ (in set). Logic: , (AND), | (OR). Special: NULL, !NULL. Example: name:lobby,deviceStatus=ONLINE

includeTeamUserNumber
boolean
Default: false

Include count of users in each team

includeTeamResourceNumber
boolean
Default: false

Include count of resources in each team

Responses

Response samples

Content type
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "size": 0,
  • "content": [
    ]
}

Create team

Create a new team (user group).

Minimum role: OWNER

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Request Body schema: application/json
required
name
required
string
comment
string
hiddenUIElementRules
string

JSON rules for hiding UI elements

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "comment": "string",
  • "hiddenUIElementRules": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "comment": "string",
  • "hiddenUIElementRules": "string",
  • "teamUserNumber": 0,
  • "teamDeviceNumber": 0,
  • "teamDeviceGroupNumber": 0,
  • "teamDeviceContentNumber": 0,
  • "teamDatasourceNumber": 0,
  • "teamContentGroupNumber": 0,
  • "teamFileNumber": 0,
  • "teamFileFolderNumber": 0,
  • "teamMessageNumber": 0,
  • "teamMessageGroupNumber": 0,
  • "teamCampaignNumber": 0,
  • "teamTopLevelCampaignNumber": 0,
  • "teamMicrosoftTenantNumber": 0,
  • "teamGoogleCredentialNumber": 0,
  • "teamAdvertiserNumber": 0,
  • "teamNotificationChannelNumber": 0,
  • "teamAlertRuleNumber": 0,
  • "teamWebhookEventActionNumber": 0,
  • "teamCustomCredentialNumber": 0
}

Update team

Update an existing team.

Minimum role: OWNER

Authorizations:
bearer
query Parameters
teamId
required
string
Request Body schema: application/json
required
name
required
string
comment
string
hiddenUIElementRules
string

JSON rules for hiding UI elements

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "comment": "string",
  • "hiddenUIElementRules": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "comment": "string",
  • "hiddenUIElementRules": "string",
  • "teamUserNumber": 0,
  • "teamDeviceNumber": 0,
  • "teamDeviceGroupNumber": 0,
  • "teamDeviceContentNumber": 0,
  • "teamDatasourceNumber": 0,
  • "teamContentGroupNumber": 0,
  • "teamFileNumber": 0,
  • "teamFileFolderNumber": 0,
  • "teamMessageNumber": 0,
  • "teamMessageGroupNumber": 0,
  • "teamCampaignNumber": 0,
  • "teamTopLevelCampaignNumber": 0,
  • "teamMicrosoftTenantNumber": 0,
  • "teamGoogleCredentialNumber": 0,
  • "teamAdvertiserNumber": 0,
  • "teamNotificationChannelNumber": 0,
  • "teamAlertRuleNumber": 0,
  • "teamWebhookEventActionNumber": 0,
  • "teamCustomCredentialNumber": 0
}

Get all teams (non-paginated)

Retrieve all teams without pagination.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

search
string

WBQL filter expression. Operators: : (contains), = (equals), ≠, ∉, ^ (starts with), >, ≥, <, ≤, ∈ (in set). Logic: , (AND), | (OR). Special: NULL, !NULL. Example: name:lobby,deviceStatus=ONLINE

includeTeamUserNumber
boolean
Default: false
includeTeamResourceNumber
boolean
Default: false

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete team

Delete a team.

Minimum role: OWNER

Authorizations:
bearer
path Parameters
teamId
required
string

Responses

Get user assignments for team

Get which users are assigned to a team.

Minimum role: OWNER

Authorizations:
bearer
query Parameters
teamId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get team assignments for user

Get which teams a user belongs to, including readOnly status for each.

Returns shallow DTOs with teamId, resourceId, and readOnly flag.

Minimum role: OWNER

Authorizations:
bearer
path Parameters
userEmail
required
string <email>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update team user assignments

Bulk update user assignments for a team.

Minimum role: OWNER

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

teamId
required
string
Request Body schema: application/json
required
Array of objects (SimpleStringIdResourceAssignmentParams)

Resources to add to the team

resourceIdsToRemove
Array of strings

Resource IDs to remove from the team

Responses

Request samples

Content type
application/json
{
  • "resourcesToAdd": [
    ],
  • "resourceIdsToRemove": [
    ]
}

metadata

Update one path inside a user's userMetadata document. Read it through the user GET endpoint with userMetadata explicitly selected. The same path semantics apply to the customer metadata operations, which require OWNER write access to that customer.

Metadata keys and their meaning are defined by the consuming frontend. The path below illustrates JSON traversal, not a supported UI setting; use keys and values defined by that frontend's contract. Send a JSON body such as {"path":["preferences","columns",0,"width"],"value":160} for a path write. A path has 1–32 segments: strings address literal object keys; nonnegative 32-bit integers address array indexes. The value field is required and accepts JSON null. Missing containers are created, but an intermediate scalar cannot be traversed. Array indexes must exist or equal the current length to append; gaps are rejected. A null or non-object document starts from an empty object for a path write.

To delete a path, repeat URL-encoded query parameters such as path=preferences&path=columns&path=0; do not send a DELETE body. The current container determines whether a segment is a key or index. Missing paths are no-ops; omitting the path is an error. Deleting an array element shifts later indexes, so retrying an index deletion can remove a different element. The /all operation resets the document to {}.

Users can change their own metadata even in read-only mode. Changes to another user require a non-read-only OWNER/ADMIN with permission to manage that user. Successful writes return an empty HTTP 200 response. Prefer stable object keys for independently edited values: array indexes refer to the document at write time, and a concurrent whole-document save can overwrite path changes.

Write user metadata at a path

Creates missing levels and replaces the value at the addressed path. String segments are object keys; integer segments are array indexes. Users may update their own metadata even in read-only mode. Updating another user requires a non-read-only OWNER/ADMIN with permission to manage the target user.

Minimum role: DEVICE_USER.

Authorizations:
bearer
query Parameters
email
required
string <email>
Request Body schema: application/json
required
required
Array of strings or integers [ 1 .. 32 ] items
value
required
any or null

Required JSON value. JSON null is valid; omitting value is invalid.

Responses

Request samples

Content type
application/json
{
  • "path": [
    ],
  • "value": null
}

Remove a user metadata path

An absent/empty path is rejected. Users may update their own metadata even in read-only mode. Updating another user requires a non-read-only OWNER/ADMIN with permission to manage the target user.

Minimum role: DEVICE_USER.

Authorizations:
bearer
query Parameters
email
required
string <email>
path
required
Array of strings [ 1 .. 32 ] items

Repeated query parameters, e.g. path=preferences&path=columns&path=0. Encode each segment; do not send a DELETE body.

Responses

Reset user metadata

Replaces the whole metadata document with an empty object. Users may update their own metadata even in read-only mode. Updating another user requires the existing user-management permissions.

Minimum role: DEVICE_USER.

Authorizations:
bearer
query Parameters
email
required
string <email>

Responses

notification-center

Personal Notification Center feed and custom notification management. Alert delivery channels are documented under Alerts & Notifications.

List visible notifications

Return the authenticated user's visible, unexpired, undismissed notifications. The audience can be the user's customer or the user. Notifications created before the user's account are excluded. seen is this user's own state. Requested sort is honored; without it, the order is unspecified.

Minimum role: VIEWER (read-only accounts may read).

Authorizations:
bearer
query Parameters
page
integer >= 0
Default: 0

Page index (0-based)

size
integer >= 1
Default: 20

Requested page size; server limits and endpoint overrides apply.

search
string

WBQL filter expression. Operators: : (contains), = (equals), ≠, ∉, ^ (starts with), >, ≥, <, ≤, ∈ (in set). Logic: , (AND), | (OR). Special: NULL, !NULL. Example: name:lobby,deviceStatus=ONLINE

select
string

Field projection. * = all primitives, field,field = specific, relation(fields) = nested. Example: select=*,customer(id,name)

sort
string
Example: sort=name,asc

Sort expression. Format: field,direction

  • Directions: asc, desc
  • Multiple sorts: sort=name,asc&sort=lastActivity,desc
  • Nested fields: sort=content.name,asc

Responses

Response samples

Content type
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "size": 0,
  • "content": [
    ]
}

Count unseen notifications

Count unseen notifications across the user's whole visible feed, independent of list pagination or active search filters. Minimum role: VIEWER (read-only accounts may read).

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "unseenCount": 0
}

Mark one notification as seen

Mark one available notification as seen for the current user. Unavailable, expired, or foreign IDs return HTTP 400 with key notification.error.notFound. Retrying an already seen notification is safe. Minimum role: VIEWER with write access; read-only accounts cannot change seen state.

Authorizations:
bearer
path Parameters
id
required
integer <int64>

Notification ID

Responses

Mark notifications as seen

Mark up to 500 available IDs as seen for the current user. An omitted body or null/empty ids marks all currently visible unseen notifications as seen. More than 500 explicit IDs returns HTTP 400 with key notification.error.batchTooLarge; an unavailable ID returns HTTP 400 with key notification.error.notFound. Minimum role: VIEWER with write access; read-only accounts cannot change seen state.

Authorizations:
bearer
Request Body schema: application/json
optional
ids
Array of integers or null <int64> <= 500 items [ items <int64 > ]

Null, omitted, or empty marks all visible unseen notifications as seen.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Dismiss a notification

Hide one notification from the current user's feed. Other users' feeds are unaffected. Unavailable, expired, or foreign IDs return HTTP 400 with key notification.error.notFound. Minimum role: VIEWER with write access; read-only accounts cannot dismiss.

Authorizations:
bearer
path Parameters
id
required
integer <int64>

Notification ID

Responses

Create a custom notification

Create a CUSTOM notification for the selected customer (CUSTOMER) or selected users in it (USER). USER accepts up to 500 email entries; unmatched addresses are omitted, and at least one user must match the selected customer. A target needs both entityKind and entityId and must belong to the selected customer. Omitted lifetime uses the configured retention period; a supplied value must be positive and cannot exceed that period.

Typed HTTP 400 keys include notification.error.recipientsRequired, notification.error.noRecipientsMatched, notification.error.batchTooLarge, notification.error.entityReferenceIncomplete, and notification.error.invalidLifetime.

Minimum role: OWNER with customer selector. Read-only accounts cannot create.

Authorizations:
bearer
query Parameters
customerId
required
integer <int64> >= 1

Customer whose custom notifications are managed; must be within the caller's access.

Request Body schema: application/json
required
audienceType
required
string
Enum: "CUSTOMER" "USER"

CUSTOMER addresses every user of the selected customer; USER addresses the users listed in recipientEmails.

severity
required
string
Enum: "INFO" "SUCCESS" "WARNING" "CRITICAL"
title
required
string [ 1 .. 255 ] characters

Nonblank text.

message
required
string [ 1 .. 2000 ] characters

Nonblank text.

entityKind
string
Enum: "device" "content" "file" "datasource"

Optional target kind; supply with entityId.

entityId
string <= 255 characters

Optional target ID; supply with entityKind.

recipientEmails
Array of strings

Required and capped at 500 entries for USER audience; only matching users in the selected customer receive it.

lifetimeSeconds
integer <int64> >= 1

Optional lifetime in seconds, at most the configured notification retention period.

Responses

Request samples

Content type
application/json
{
  • "audienceType": "CUSTOMER",
  • "severity": "INFO",
  • "title": "string",
  • "message": "string",
  • "entityKind": "device",
  • "entityId": "string",
  • "recipientEmails": [
    ],
  • "lifetimeSeconds": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "type": "ALERT_DEVICES",
  • "severity": "INFO",
  • "createdBy": "string",
  • "title": "string",
  • "message": "string",
  • "titleKey": "string",
  • "messageKey": "string",
  • "params": {
    },
  • "entityKind": "device",
  • "entityId": "string",
  • "createdAt": 1683802510000,
  • "expiresAt": 1683802510000,
  • "seen": true
}

List managed custom notifications

List CUSTOM notifications owned by the selected customer. This management list is separate from the authenticated user's personal feed and includes audience and recipient-state details. Minimum role: OWNER with customer selector.

Authorizations:
bearer
query Parameters
customerId
required
integer <int64> >= 1

Customer whose custom notifications are managed; must be within the caller's access.

page
integer >= 0
Default: 0

Page index (0-based)

size
integer >= 1
Default: 20

Requested page size; server limits and endpoint overrides apply.

search
string

WBQL filter expression. Operators: : (contains), = (equals), ≠, ∉, ^ (starts with), >, ≥, <, ≤, ∈ (in set). Logic: , (AND), | (OR). Special: NULL, !NULL. Example: name:lobby,deviceStatus=ONLINE

sort
string
Example: sort=name,asc

Sort expression. Format: field,direction

  • Directions: asc, desc
  • Multiple sorts: sort=name,asc&sort=lastActivity,desc
  • Nested fields: sort=content.name,asc
select
string

Field projection. * = all primitives, field,field = specific, relation(fields) = nested. Example: select=*,customer(id,name)

Responses

Response samples

Content type
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "size": 0,
  • "content": [
    ]
}

Get a managed custom notification

Read one CUSTOM notification in the caller's management scope. An unavailable or out-of-scope ID returns HTTP 404 with key notification.error.notFound. Minimum role: OWNER with customer selector.

Authorizations:
bearer
path Parameters
notificationId
required
integer <int64>

Managed notification ID

query Parameters
customerId
required
integer <int64> >= 1

Customer whose custom notifications are managed; must be within the caller's access.

select
string

Field projection. * = all primitives, field,field = specific, relation(fields) = nested. Example: select=*,customer(id,name)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "type": "ALERT_DEVICES",
  • "severity": "INFO",
  • "createdBy": "string",
  • "title": "string",
  • "message": "string",
  • "titleKey": "string",
  • "messageKey": "string",
  • "params": {
    },
  • "entityKind": "device",
  • "entityId": "string",
  • "createdAt": 1683802510000,
  • "expiresAt": 1683802510000,
  • "seen": true,
  • "customerId": 0,
  • "createdByUser": {
    },
  • "seenCount": 0,
  • "audiences": [
    ]
}

Delete a custom notification for its audience

Permanently remove one manageable CUSTOM notification for all its recipients. Personal dismissal uses DELETE /api/notifications/{id} instead. An unavailable or out-of-scope ID returns HTTP 404 with key notification.error.notFound. Minimum role: OWNER with customer selector.

Authorizations:
bearer
path Parameters
notificationId
required
integer <int64>

Managed notification ID

query Parameters
customerId
required
integer <int64> >= 1

Customer whose custom notifications are managed; must be within the caller's access.

Responses

Recreate a custom notification

Replace a manageable CUSTOM notification with a new one. The original audience, ownership, and target are retained; title, message, severity, and optional lifetime describe the replacement. Recipient seen and dismissal state resets. If lifetime is omitted, the original total lifetime is used from the replacement's creation time. An unavailable or out-of-scope ID returns HTTP 404 with key notification.error.notFound. Minimum role: OWNER with customer selector.

Authorizations:
bearer
path Parameters
notificationId
required
integer <int64>

Managed notification ID

query Parameters
customerId
required
integer <int64> >= 1

Customer whose custom notifications are managed; must be within the caller's access.

Request Body schema: application/json
required
severity
required
string
Enum: "INFO" "SUCCESS" "WARNING" "CRITICAL"
title
required
string [ 1 .. 255 ] characters

Nonblank text.

message
required
string [ 1 .. 2000 ] characters

Nonblank text.

lifetimeSeconds
integer <int64> >= 1

Optional lifetime in seconds, at most the configured notification retention period.

Responses

Request samples

Content type
application/json
{
  • "severity": "INFO",
  • "title": "string",
  • "message": "string",
  • "lifetimeSeconds": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "type": "ALERT_DEVICES",
  • "severity": "INFO",
  • "createdBy": "string",
  • "title": "string",
  • "message": "string",
  • "titleKey": "string",
  • "messageKey": "string",
  • "params": {
    },
  • "entityKind": "device",
  • "entityId": "string",
  • "createdAt": 1683802510000,
  • "expiresAt": 1683802510000,
  • "seen": true
}