Settings

Manage your account: profile and password, API keys, notification preferences, unit preferences, and your team's members and roles. All endpoints are authenticated with a Bearer JWT (see Authentication).

Endpoints

Method	Path	Description
PATCH	/api/v1/settings/profile	Update your profile
POST	/api/v1/settings/change-password	Change your password
POST	/api/v1/settings/logout-other-sessions	Sign out your other devices
POST	/api/v1/api-keys	Create an API key (Admin)
GET	/api/v1/api-keys	List API keys
DELETE	/api/v1/settings/api-keys/{key_id}	Revoke an API key (Admin)
GET	/api/v1/settings/email-notifications	Get email notification preferences
PATCH	/api/v1/settings/email-notifications	Update email notification preferences (Admin)
GET	/api/v1/settings/report-schedule	Get scheduled-report settings
PATCH	/api/v1/settings/report-schedule	Update scheduled-report settings
GET	/api/v1/units/supported	List supported units and conversions
GET	/api/v1/settings/units	Get unit preferences
PATCH	/api/v1/settings/units	Update unit preferences
GET	/api/v1/users	List team members (Admin)
POST	/api/v1/users	Add a team member (Admin)
POST	/api/v1/users/invite	Invite a team member by email (Admin)
PATCH	/api/v1/users/{user_id}	Update a team member's details (Admin)
PUT	/api/v1/users/{user_id}/role	Change a team member's role (Admin)
DELETE	/api/v1/users/{user_id}	Deactivate a team member (Admin)
GET	/api/v1/settings/roles	List roles
POST	/api/v1/settings/roles	Create a custom role (Admin)
PATCH	/api/v1/settings/roles/{key}	Update a role (Admin)
DELETE	/api/v1/settings/roles/{key}	Delete a custom role (Admin)

Endpoints marked Admin require an account administrator role.

Profile

Update your profile

PATCH /api/v1/settings/profile

{
  "full_name": "Jane Smith",
  "email": "jane@example.com",
  "current_password": "your-current-password",
  "phone": "+1 555 0100",
  "timezone": "America/New_York",
  "locale": "en-US"
}

Changing your email requires current_password. All fields are optional; send an empty string to clear an optional field.

Change your password

POST /api/v1/settings/change-password

{ "current_password": "old-password", "new_password": "NewSecureP@ss123!" }

Changing your password signs out your other devices and returns a fresh access token so your current device stays signed in.

Sign out other sessions

POST /api/v1/settings/logout-other-sessions

Signs out every other device while keeping the current one signed in.

API keys

API keys authenticate machine-to-machine access, such as the edge agent or a data-ingestion script. See the API Keys guide.

Create an API key

POST /api/v1/api-keys — the request body is just a name:

{ "name": "edge-agent-prod" }

The response (201 Created) returns the secret once:

{
  "id": "...",
  "name": "edge-agent-prod",
  "key": "hlts_…",
  "created_at": "2026-08-05T10:00:00Z"
}

warning

The key value is shown only once, at creation. Store it securely; it cannot be retrieved again.

List and revoke

GET /api/v1/api-keys returns your keys with only a masked key_prefix — never the secret — plus is_active and created_at. DELETE /api/v1/settings/api-keys/{key_id} revokes a key immediately.

Notification preferences

Email notifications

GET /api/v1/settings/email-notifications returns each toggleable transactional email and whether it is enabled. PATCH accepts a partial map and merges it.

{ "prefs": { "role_changed": true, "password_changed": true } }

Scheduled reports

GET / PATCH /api/v1/settings/report-schedule controls automatic report delivery.

{
  "report_schedule": "weekly",
  "report_emails": ["reports@example.com", "ops@example.com"]
}

report_schedule is daily, weekly, monthly, or null (disabled).

Unit preferences

GET /api/v1/units/supported lists every supported unit and conversion pair plus the defaults. GET / PATCH /api/v1/settings/units reads and updates your account's preferred display units.

{ "unit_preferences": { "temperature": "fahrenheit", "pressure": "bar" } }

Team members

Account administrators manage who has access.

Add a team member

POST /api/v1/users

{ "email": "operator@example.com", "password": "TempP@ss123!", "full_name": "John Doe", "role": "operator" }

Invite a team member

POST /api/v1/users/invite creates a pending account and emails an invitation link; the invitee sets their own password to activate.

{ "email": "colleague@example.com", "full_name": "Chris Lee", "role": "viewer" }

Change a member's role

PUT /api/v1/users/{user_id}/role

{ "role": "admin" }

Deactivate a member

DELETE /api/v1/users/{user_id} deactivates a member. You cannot deactivate your own account.

Roles

Roles bundle a level of access you can assign to team members. GET /api/v1/settings/roles lists the built-in roles and any custom roles you have created, along with how many members hold each.

Create a custom role

POST /api/v1/settings/roles

{ "name": "Line Lead", "base_tier": "operator" }

Give the role a name and a starting access level (admin, operator, or viewer). Use PATCH /api/v1/settings/roles/{key} to rename it and DELETE /api/v1/settings/roles/{key} to remove a custom role.