Manage the users in the subscription. XML responses provide details about each user such as the user’s login ID, account info, assigned asset groups, and permissions. Session-based authentication is not supported using this API.
When the API request is made by a Manager or Unit Manager, the last login date for each user is provided in the XML results. This is the most recent date and time the user logged into the service. For a Manager, the last login date appears for all users in the subscription. For a Unit Manager, the last login date appears for all users in the Unit Manager’s same business unit.
Use the following APIs to get details of all users.
When a new user account is created, the service by default sends the user an email titled “Registration - Start Now”. This email includes a secure link to the user's login information - platform URL and login credentials. Instead of sending an email notification, the API user has the option to return login credentials using user.php function with the send_email=0 input parameter.
The user must complete the first login to the service in order to complete the account registration and accept the Qualys EULA (End User License Agreement). When the first login is completed, the service sends the user an email titled “Registration - Complete”.
A new user has the option to complete the first login by simply logging into the Qualys user interface, as long as the user is granted the GUI access method. (Note a new user created using the user.php function is automatically granted the GUI and API access methods.) Using the Qualys user interface, the user is directed to the First Login form to complete the registration and accept the Qualys EULA.
The acceptEULA.php API function is provided as a programmatic method for completing the registration and accepting the Qualys EULA. To use complete the first login using the acceptEULA.php function, the user must submit an API request using their platform URL and login credentials.
API access method only - If a new user account is created using the Qualys user interface and the account is granted the API access method only (without the GUI access method), the user must complete the first login using the acceptEULA.php API function. If the acceptEULA.php API request is not made or it is not successful, the new account will not be activated and any API requests submitted using the new account will fail.
Parameters used to define Qualys users (sub-accounts) using the Users API are below. If the same parameter is specified multiple times when adding or updating a user account, typically the last instance overrides the rest.
|
Parameter |
Description |
|---|---|
|
Permissions |
|
|
user_role={role} |
Specifies the user role. A valid value is: manager, unit_manager, scanner, reader, contact or administrator. The first user added to a new custom business unit must be unit_manager. Add request: Required (Invalid for Express Lite user) Edit request: Invalid |
|
business_unit={title} |
Specifies the user’s business unit. A valid value is “Unassigned”, or the title of an existing custom business unit. Note a custom business unit may be added using the Qualys user interface. Add request: Required (Invalid for Express Lite user) Edit request: Invalid |
|
asset_groups={grp1,grp2...} |
Specifies the asset groups assigned to the user, when the user role is Scanner, Reader or Contact. Multiple asset groups are comma separated. This parameter is invalid when the user role is Manager or Unit Manager. Add request: Optional | Edit request: Optional |
|
General Info |
|
|
first_name={name} |
Specifies the user's first name. The name may include a maximum of 50 characters. Add request: Required | Edit Request: Optional |
|
last_name={name} |
Specifies the user's last name. The name may include a maximum of 50 characters. Add request: Required | Edit request: Optional |
|
title={title} |
Specifies the user's job title. The title may include a maximum of 100 characters. Add request: Required | Edit request: Optional |
|
phone={value} |
Specifies the user's phone number. This value may include a maximum of 40 characters. Add request: Required | Edit request: Optional |
|
fax={value} |
The user's FAX number. This value may include a maximum of 40 characters. Add request: Optional | Edit request: Optional |
|
email={value} |
Specifies the user's email address. The address must be a properly formatted address with a maximum of 100 characters. Add request: Required | Edit request: Optional |
|
address1={value} |
Specifies the user’s address line 1. This value may include a maximum of 80 characters. Add request: Required | Edit request: Optional |
|
address2={value} |
Specifies the user’s address line 2. This value may include a maximum of 80 characters. Add request: Optional | Edit request: Optional |
|
city={value} |
Specifies the user’s city. This value may include a maximum of 50 characters. Add request: Required | Edit request: Optional |
|
country={code} |
Specifies the user’s country code. View Country Codes Add request: Required | Edit request: Optional |
|
state={code} |
Specifies the user’s state code. A valid value depends on the country code specified for the country parameter. You must enter a state code using the state parameter when the country code is one of: “United States of America”, “Australia”, “Canada” or “India”. View State Codes For other country codes, a state code does not need to be specified. If specified, enter the state code “none”. Add request: Required for some country codes | Edit request: Optional |
|
zip_code={zipcode} |
(Optional) Specifies the user’s zip code. This value may include a maximum of 20 characters. If not specified, this is set to the zip code in the API user’s account. |
|
external_id={value} |
A custom external ID value. The external ID value can have a maximum of 256 characters, and it is case sensitive. The characters can be in uppercase, lowercase or mixed case. HTML or PHP tags cannot be included. Specify external_id= or external_id=”” to delete an external ID value from an existing account. Add request: Optional | Edit request: Optional |
|
time_zone_code={value} |
Set user profile to a time zone code i.e. US-NY. To set the profile to the browser's timezone pass empty/null, i.e. time_zone_code=" Looking for timezone codes? Run <platform API server>/msp/time_zone_code_list.php Add request: Optional | Edit request: Optional |
User permissions required to manage Qualys users (add, edit, view) are below.
|
User role |
Permissions |
|---|---|
|
Manager |
Add and edit all user accounts in the subscription. View all user accounts in subscription, including full user details. |
|
Administrator |
Add and edit user accounts except Manager and Administrator user. View all user accounts in subscription, including full user details. |
|
Unit Manager |
Add and edit user accounts to API user’s same business unit. View user accounts for users in their business unit, including full user details. See Unit Manager permissions |
|
Scanner, Reader, Auditor |
No permissions |
Unit Managers can view full user account details for users in their business unit. Unit Managers may also be able to view partial user account details for users outside of their business unit. This is determined by a subscription level permission set by Managers in the user interface.
If “Restrict view of user information for users outside of business unit” is not selected (the default), then Unit Managers have an unrestricted view and can see partial details about users who are not in their assigned business unit.
When a list users API request is made by a Manager or Unit Manager, the last login date for each user is provided in the XML results. This is the most recent date and time the user logged into the service. For a Manager, the last login date appears for all users in the subscription. For a Unit Manager, the last login date appears for all users in the Unit Manager’s same business unit.