Overview

The Users REST API lets external systems manage the end users of your self-hosted DronaHQ account: list and look up users, create users, assign or remove groups, and activate or deactivate users. It is useful for keeping DronaHQ in sync with an HR system, a CRM or any other source of truth for your users.

If you use an identity provider such as Okta or Microsoft Entra, consider the SCIM 2.0 REST API instead — it covers the same operations using the SCIM standard.

Base URL

All endpoints are served under the /api/public prefix on your BUILDER_URL — the same URL you use to open the admin console:

<BUILDER_URL>/api/public/users

Authentication

Every request must include your account's DronaHQ API Key (Account Token) as a bearer token in the request header:

Headers

Key	Value
Authorization	Bearer <Account API Key>

To find or regenerate the key, go to Account → Integrations and look for DronaHQ API Key (Account Token). Only account owners and administrators can view it.

• The key is scoped to a single account. All endpoints operate only on users and groups that belong to that account.
• Per-app tokens are not accepted by the Users REST API.
• The key must be sent in the Authorization header. Passing it in the request body or as a query parameter is not supported.

A missing or invalid key returns 401:

{
    "error": 401,
    "message": "Authorization failed.",
    "reason": "Token not found."
}

Endpoints

Endpoint	Description
GET /api/public/users	List users in the account
GET /api/public/users/{user_id_or_email}	Get a single user by id or email
POST /api/public/users	Create or invite up to 50 users
PUT /api/public/users/{user_id}/actions/change_group	Assign groups to a user or remove groups from a user
PUT /api/public/users/activate	Reactivate deactivated users
DELETE /api/public/users/deactivate	Deactivate users

User object

The list and get endpoints return users in the following shape:

Field	Type	Description
user_id	Integer	Unique id of the user
user_name	String	Full name of the user
user_email	String	Email address of the user
user_desg	String	Designation of the user
user_image_url	String	Profile image URL of the user
channel_id	Integer	Id of the account the user belongs to
channel_name	String	Unique name of the account the user belongs to
app_name	String	Display name of the account
user_reg_date	String	Date and time the user was registered
user_last_app_activity	String	Date and time of the user's last app launch. Only populated by the get-user endpoint.
user_group	Array	Groups the user belongs to, as { "grp_id": 5, "grp_name": "Sales" } objects
is_admin	Boolean	true if the user is an account administrator
stats	Object	Activity summary — status, available_content, consumed_content, app_timespent. Populated only when stats are requested.

Errors

Error responses are JSON objects with the HTTP status in error, a short message and a more specific reason:

{
    "error": 404,
    "message": "User not found.",
    "reason": ""
}

Several endpoints accept a list of users or groups and process them independently. Those endpoints return 200 even when some entries could not be processed, and report the failed entries in the response body — check the per-endpoint documentation for the exact fields.