Directory

Server

Org/site CRUD.

Create a new org, plus its first admin user, in one call

POST

http://localhost:8080/auth

/orgs

Public - no token required. A brand-new org has to be creatable with zero prior credentials; there's no other admin who could have authorized it. Rate-limited per source IP at the gateway (5/min) since it's the one mutating route this API exposes without a token.

Create a new org, plus its first admin user, in one call › Request Body

name

string · required

admin_email

string · email · required

admin_password

string · required

Create a new org, plus its first admin user, in one call › Responses

Created.

id

string

name

string

admin_user_id

string

The caller's org's sites

GET

http://localhost:8080/auth

/sites

admin-only. For picking the sites a user is limited to.

The caller's org's sites › Responses

Sites, by name.

object[]

id

string

name

string

topic_prefixes

string[]

Create a site under the caller's own org

POST

http://localhost:8080/auth

/sites

admin-only. org_id is the caller's own org, taken from their token - not a request field.

Create a site under the caller's own org › Request Body

name

string · required

topic_prefixes

string[]

Topic prefixes this site owns (e.g. fbf/hospital-a): its points and equipment are the ones under them. Once any site has a prefix, reads are scoped to the caller's sites. Must not overlap another org's prefixes.

Create a site under the caller's own org › Responses

Created.

id

string

org_id

string

name

string

topic_prefixes

string[]

broker_accounts_updated

integer

The site's edge-node broker accounts re-applied with the new prefixes.

broker_error

string

Set when the prefixes were saved but the MQTT broker couldn't be updated; the site's edge nodes keep their old permissions until the next change.

Replace the topic prefixes a site owns

PUT

http://localhost:8080/auth

/sites/{site_id}/topic-prefixes

admin-only, for a site in the caller's own org. Prefixes must not overlap another org's.

Replace the topic prefixes a site owns › path Parameters

site_id

string · required

Replace the topic prefixes a site owns › Request Body

topic_prefixes

string[] · required

Replace the topic prefixes a site owns › Responses

Updated.

Site

id

string

org_id

string

name

string

topic_prefixes

string[]

The users in the caller's own org

GET

http://localhost:8080/auth

/users

admin-only. Never includes password hashes.

The users in the caller's own org › Responses

Users, by email.

object[]

id

string

email

string

role

string

created_at

string · date-time

site_ids

string[]

disabled

boolean

Can't log in until enabled again.

display_name

string | null

How the person signs; null when unset

Add a user to the caller's own org

POST

http://localhost:8080/auth

/users

admin-only. org_id is the caller's own org, taken from their token. For a brand-new org's first user, use POST /orgs instead - this endpoint needs an existing admin to call it.

Add a user to the caller's own org › Request Body

email

string · email · required

Trimmed and lower-cased.

password

string · minLength: 12 · required

role

string · enum · required

Enum values:

admin

operator

viewer

display_name

string | null · maxLength: 120

How the person signs, e.g. Jacob Nash (Cx waivers name them by it)

site_ids

string[]

Limit the user to these sites (from GET /sites). Omit or empty for the whole org.

Add a user to the caller's own org › Responses

Created.

id

string

org_id

string

email

string

role

string

display_name

string | null

site_ids

string[]

Remove a user from the caller's org

DELETE

http://localhost:8080/auth

/users/{user_id}

admin-only, own org only. Also ends the user's live sessions at the gateway (within its 30s denylist refresh). You can't delete your own account.

Remove a user from the caller's org › path Parameters

user_id

string · required

Remove a user from the caller's org › Responses

Deleted.

No data returned

Change a user's role, sites or display name, or disable/enable them

PATCH

http://localhost:8080/auth

/users/{user_id}

admin-only, own org only. Role and sites are carried in the user's session token, so their sessions end and they log in again (a display_name change alone leaves them signed in); disabling also ends them, and a disabled user's login (password or Haystack SCRAM) fails exactly like a wrong password. You can't change your own role or disable yourself, and the org's last active admin can't be demoted or disabled.

Change a user's role, sites or display name, or disable/enable them › path Parameters

user_id

string · required

Change a user's role, sites or display name, or disable/enable them › Request Body

role

string · enum

Enum values:

admin

operator

viewer

site_ids

string[]

Empty = the whole org.

disabled

boolean

display_name

string | null · maxLength: 120

How the person signs, e.g. Jacob Nash; null or blank clears it

Change a user's role, sites or display name, or disable/enable them › Responses

Updated.

id

string

role

string

site_ids

string[]

disabled

boolean

display_name

string | null

Set a user's password (admin reset)

PUT

http://localhost:8080/auth

/users/{user_id}/password

admin-only, own org only. Ends every session the user had; they log in again with the new password.

Set a user's password (admin reset) › path Parameters

user_id

string · required

Set a user's password (admin reset) › Request Body

password

string · required

Set a user's password (admin reset) › Responses

Changed.

No data returned

API keys Edge nodes

Baler Auth API