User endpoints

All endpoints live under /api/v1/users and require the Admin role or higher. There is no standalone “change role” endpoint — role is one of the fields accepted by PATCH /api/v1/users/{id}. There is no bulk “revoke all sessions” endpoint — call DELETE /api/v1/users/{id}/sessions/{sid} once per session.

`GET /api/v1/users`

List users in the caller’s org.

Since: v1.0 Required role: admin

Query parameters

Name	Type	Default	Constraints
`cursor`	string	null	Pagination cursor
`limit`	int	20	1-100

Response 200

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "ops@acme-logistics.com",
      "display_name": "Jordan Park",
      "role": "operator",
      "enabled": true,
      "created_at": "2026-02-10T14:32:00Z"
    }
  ],
  "next_cursor": null,
  "total": 1
}

Error responses

Code	Body.error	Meaning
401	`auth_required`	Missing or invalid token
403	`forbidden`	Caller is not Admin or above

Examples

curl -H "Authorization: Bearer sk_live_abc123" \
  https://novavms.novalien.com/api/v1/users

const users = await novavms.users.list();

users = client.users.list()

`POST /api/v1/users`

Invite a new user. Sends an invitation email if SendGrid is configured.

Since: v1.0 Required role: admin

Request body

Name	Type	Default	Constraints
`email`	string	—	RFC 5321 mailbox; unique per org
`display_name`	string	—	1-100 chars
`role`	enum	—	`owner`, `admin`, `operator`, `viewer` (D78)
`site_ids`	uuid[]	`[]`	Required for viewers; ignored for other roles

Response 201

{
  "user": {
    "id": "7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c",
    "email": "viewer@acme-logistics.com",
    "display_name": "Casey Lee",
    "role": "viewer",
    "enabled": true
  },
  "invitation_sent": true
}

Error responses

Code	Body.error	Meaning
400	`validation_error`	Missing field or invalid role
409	`conflict`	Email already exists in org
403	`forbidden`	Caller is not Admin or above

Examples

curl -X POST https://novavms.novalien.com/api/v1/users \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"email":"viewer@acme-logistics.com","display_name":"Casey Lee","role":"viewer","site_ids":["b5e9f3a1-2c4d-4e6f-8a1b-3c5d7e9f1a2b"]}'

const invited = await novavms.users.create({
  email: 'viewer@acme-logistics.com',
  displayName: 'Casey Lee',
  role: 'viewer',
  siteIds: ['b5e9f3a1-2c4d-4e6f-8a1b-3c5d7e9f1a2b'],
});

invited = client.users.create(
    email="viewer@acme-logistics.com",
    display_name="Casey Lee",
    role="viewer",
    site_ids=["b5e9f3a1-2c4d-4e6f-8a1b-3c5d7e9f1a2b"],
)

`GET /api/v1/users/{id}`

Return a single user.

Since: v1.0 Required role: admin

Response 200

{
  "id": "7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c",
  "email": "viewer@acme-logistics.com",
  "display_name": "Casey Lee",
  "role": "viewer",
  "enabled": true,
  "created_at": "2026-04-01T09:00:00Z"
}

Error responses

Code	Body.error	Meaning
401	`auth_required`	Missing or invalid token
403	`forbidden`	Caller is not Admin or above
404	`not_found`	User not in caller’s org

Examples

curl -H "Authorization: Bearer sk_live_abc123" \
  https://novavms.novalien.com/api/v1/users/7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c

const user = await novavms.users.get('7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c');

user = client.users.get("7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c")

`PATCH /api/v1/users/{id}`

Update display_name, role, or enabled. Any other field is silently dropped. Use this to change a user’s role.

Since: v1.0 Required role: admin

Request body

Name	Type	Default	Constraints
`display_name`	string	—	1-100 chars
`role`	enum	—	`owner`, `admin`, `operator`, `viewer`
`enabled`	bool	—	`false` soft-disables sign-in

Response 200

{
  "id": "7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c",
  "email": "viewer@acme-logistics.com",
  "display_name": "Casey Lee",
  "role": "operator",
  "enabled": true
}

Error responses

Code	Body.error	Meaning
400	`validation_error`	Invalid role or empty body
403	`forbidden`	Demoting the sole Owner is forbidden
404	`not_found`	User not in caller’s org

Examples

curl -X PATCH https://novavms.novalien.com/api/v1/users/7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"role":"operator"}'

await novavms.users.update('7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c', {
  role: 'operator',
});

client.users.update("7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c", role="operator")

`DELETE /api/v1/users/{id}`

Disable the user. This is a soft-delete — audit trail and event history are preserved; the user can no longer sign in.

Since: v1.0 Required role: admin

Response 200

{"message": "user disabled"}

Error responses

Code	Body.error	Meaning
403	`forbidden`	Disabling the sole Owner is forbidden
404	`not_found`	User not in caller’s org

Examples

curl -X DELETE https://novavms.novalien.com/api/v1/users/7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c \
  -H "Authorization: Bearer sk_live_abc123"

await novavms.users.disable('7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c');

client.users.disable("7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c")

`DELETE /api/v1/users/{id}/sessions/{sid}`

Revoke a single active session for a user. To revoke all sessions, list them first via GET /api/v1/users/{id}/sessions and call this endpoint once per entry.

Since: v1.0 Required role: admin

Response 200

{"message": "session revoked"}

Error responses

Code	Body.error	Meaning
403	`forbidden`	Caller is not Admin or above
404	`not_found`	User or session ID unknown in caller’s org

Examples

curl -X DELETE https://novavms.novalien.com/api/v1/users/7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c/sessions/9c2d1e0f-3a4b-4c5d-6e7f-8a9b0c1d2e3f \
  -H "Authorization: Bearer sk_live_abc123"

await novavms.users.revokeSession(
  '7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c',
  '9c2d1e0f-3a4b-4c5d-6e7f-8a9b0c1d2e3f',
);

client.users.revoke_session(
    "7a3f4c1e-9b8d-4e2f-a6c5-3d8e9f0a1b2c",
    "9c2d1e0f-3a4b-4c5d-6e7f-8a9b0c1d2e3f",
)