Skip to main content
A user is a person in your Lumos organization, and one kind of identity. Users hold accounts on your apps, and an account’s user_id is the id of the user it belongs to. v1 reads users but doesn’t create or edit them. The only change v1 makes to a user is through the roles endpoints, which add and remove the user’s Lumos roles.
The User object

​
Attributes

Get Current User returns the same object without custom_attributes.

​
Custom attributes

Pass expand=custom_attributes to List Users or Get User to include custom_attributes. Each value carries a type of text or user. A user value is an array of user objects. It’s empty when Lumos can’t find the user it points to.

​
Finding users

List Users returns users sorted by name. search matches a name or an email. Add exact_match=true to return only users whose name or email equals search. A page can hold fewer users than page_size while more remain, so stop only when next_page_token is missing or null, as Pagination describes. Get Current User returns the user who owns the calling token. Use it to check which user a token acts as.

​
Unknown and deleted users

A user ID returns 404 when it doesn’t match a user in your organization, or when it belongs to a user that Lumos has removed from your organization. List Users omits removed users, and requests for their accounts or roles also return 404. No parameter includes them.

​
Accounts

List User Accounts returns the accounts one user holds. They’re the same Account objects that List Accounts returns, and expand=app adds each account’s app.

​
Roles

List User Roles returns the user’s id as user_id and their roles as roles, a list of role objects:
resource_type is one of app, dashboard, access-policy, vendor, non-human-identity, task, or discovered-credential. It names a type only. The role object doesn’t say which apps, vendors, or other resources the role covers. Add User Role and Remove User Role take the role’s id in the path:
role_id is a built-in role’s id from the table below, or a custom role’s id from List User Roles. Naming a built-in role by its v0 name, such as APP_ADMIN, returns 400 with code set to role.id_required. Two more built-in roles, lumos-internal-user and vendor-qa-user, are reserved for internal Lumos use. Add User Role and Remove User Role return 403 for either one, but List User Roles can still return them for a user Lumos assigned them to. Any other value returns 400, including a role’s label and a custom role’s name. Add User Role returns 201. When Lumos adds the role, the body has role_added, which is the role object for it. When the user already holds the role, nothing changes, and the body has message instead. message names the role by its label. Remove User Role returns 204 whether or not the user held the role, so both calls are safe to retry. Of the built-in roles, Admin and Read Only Admin can read any user’s roles, and only Admin can add or remove any role. App Admin can add or remove only the App Admin role.

​
Endpoints