Users API

Users API

The Users API lets you query and manage user records. All endpoints require a valid JWT in the Authorization: Bearer <token> header — see API Authentication for how to obtain one.

For the complete, always-current list of endpoints, parameters, and response fields for the version you are running, use the interactive OpenAPI (Swagger) interface at https://<your-octoja-instance>/openapi/index.html. This article keeps only the permissions, behaviors, and validation rules that the schema cannot express.

Endpoints

Get the current user

GET /api/users/me returns a session-scoped view of the authenticated caller whose shape differs from the regular User object: the email field is named email (not mailAddress), the full groups objects are returned with their resolved permissions (not just groupIds), and an additional preferences field is included. Field-by-field details are in Swagger.

Creating a user

Requires the users.manage permission. Required: mailAddress (the login email address, which must be unique) and lastname. firstname and password are optional; the full field list is in Swagger.

If you create a user without a password, that user has no local password login and needs a linked OIDC / SSO login before they can sign in. A common example is Microsoft SSO. For Microsoft SSO, the first sign-in may require a Microsoft administrator in the Microsoft tenant to grant consent for octoja.

Updating a user

POST /api/users/{id}

Requires the users.manage permission. Send only the fields you want to change. Each field is wrapped in an UpdateValue<T> envelope of the shape { "hasValue": true, "value": <T> }; omit the field entirely to leave it untouched. Sending a bare value (for example "newFirstname": "Max") is rejected as a deserialization error. The full updatable-field list is in Swagger; the fields below carry behavior worth knowing:

{  "newFirstname": { "hasValue": true, "value": "Max" },  "newPassword": { "hasValue": true, "value": null }}

• newMailAddress — new login email address; must be unique.
• newPassword — a value of null removes the local password login, making the account SSO-only unless a new password is set later.
• newFirstname / newLastname — a value of null clears the name.
• newGroupIds — replaces the full group assignment list (not a partial add/remove).
• newTotpSecret — a value of null disables TOTP.
• oidcProvidersToUnlink — OIDC providers to unlink, for example ["Microsoft"].

Validation rules

• newMailAddress with an empty or whitespace-only value, or one already used by another user, returns 400 Bad Request.
• newPassword with an empty or whitespace-only value returns 400 Bad Request — use null to remove the password.
• newGroupIds containing an unknown group ID returns 400 Bad Request.
• A group change that would remove the last effective groups.manage capability is rejected by the safety guard.

Deleting a user

Requires the users.manage permission. The same safety guard applies: deleting a user is rejected if it would leave no remaining member of a group with the groups.manage permission.

Update your own profile

POST /api/users/me is available to every authenticated user — no users.manage permission required. Fields use the same UpdateValue<T> envelope as "Updating a user" and the endpoint returns the updated user. Behaviors worth knowing:

• newFirstname — a value of null or an empty string clears it.
• newLastname — an empty or whitespace-only value is rejected with 400 Bad Request.
• newTotpSecret — a value of null disables TOTP.
• oidcProvidersToUnlink — unlink your own OIDC sign-ins, for example ["Microsoft"]. Rejected with 400 Bad Request if it would leave you with no way to sign in (no local password and no remaining linked login).

Change your own password

POST /api/users/me/change-password

Available to every authenticated user. This endpoint uses plain fields (currentPassword, newPassword), not the UpdateValue envelope. It returns 400 Bad Request if either field is empty, if the account has no local password set, or if currentPassword is incorrect. On success the response is 204 No Content.

Remove your own password

DELETE /api/users/me/password

Available to every authenticated user. This removes your local password so the account signs in through SSO only. It returns 400 Bad Request if no password is set, or if the account has no linked OIDC login — octoja always keeps at least one sign-in method, so you cannot remove the password from an account that has no other way to sign in. On success the response is 204 No Content.

Update your preferences

POST /api/users/me/preferences is available to every authenticated user and updates the preferences object returned by GET /api/users/me. It returns the updated preferences object. Behaviors worth knowing:

• toggleFavoriteAssetId — toggles the device in the favorites list: adds it if absent, removes it if present. Maximum 100 favorites; adding beyond that is rejected with 400 Bad Request.
• startPage — the page shown after sign-in. One of a fixed set of values (Dashboard, Cases, Devices, Customers, PatchCycles); default Dashboard.
• openDevicesInNewTab — whether device links open in a new browser tab.

Fields worth knowing

The full User object is documented field-by-field in Swagger. A few fields carry behavior that is easy to miss:

• mailAddress — the login email address on the standard User object; note GET /api/users/me returns this as email instead.
• groupIds — the IDs of the groups this user belongs to; the resolved group objects with permissions are returned only by GET /api/users/me.
• hasPassword / hasTotpSecret — booleans that report whether a local password or TOTP is set, without exposing the secret.
• oidcLogins — linked OIDC sign-ins; each entry carries providerId (for example Microsoft), subjectId, and linkedAt.