Tenable.sc API: User

/user

Methods
GET

Gets the list of Users. Depending on your role, this resource will return the following:

  • A list of all Administrators (by default if the session user has the Administrator Role) or a list of all SecurityManagers (if the session user is an Administrator and the optional field orgID is provided) in the provided organization.
  • A list of all Users within the Organization's context if the session user is not an Administrator, depending on access and permissions
Fields Parameter
Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,...

Allowed Fields

*id
**username
**firstname
**lastname
**status
role
title
email
address
city
state
country
phone
fax
createdTime
modifiedTime
lastLogin
lastLoginIP
mustChangePassword
locked
failedLogins
authType
fingerprint
password
description
canUse
canManage
managedUsersGroups
managedObjectsGroups
preferences

ldaps
ldapUsername

Session user is not role "1" (Administrator)

responsibleAsset
group

Legend

* = always comes back

** = comes back if fields list not specified on GET all

 Request User Parameters
Expand

Session user is an Administrator

{
	"orgID" : <number> OPTIONAL
}

Session user is not an Administrator

None

Example Response
Administrator
Expand
{
	"type" : "regular",
	"response" : [
		{
			"id" : "1",
			"status" : "0",
			"username" : "admin",
			"ldapUsername" : "",
			"firstname" : "Admin",
			"lastname" : "User",
			"title" : "Application Administrator",
			"email" : "",
			"address" : "",
			"city" : "",
			"state" : "",
			"country" : "",
			"phone" : "",
			"fax" : "",
			"createdTime" : "1432921843",
			"modifiedTime" : "1453473716",
			"lastLogin" : "1454350174",
			"lastLoginIP" : "172.20.0.0",
			"mustChangePassword" : "false",
			"locked" : "false",
			"failedLogins" : "0",
			"authType" : "tns",
			"fingerprint" : null,
			"password" : "SET",
			"preferences" : [
				{
					"name" : "timezone",
					"value" : "America/New_York",
					"tag" : ""
				}
			],
			"canUse" : true,
			"canManage" : true,
			"role" : {
				"id" : "1",
				"name" : "Administrator",
				"description" : "Role defining an administrator of the application"
			},
			"ldap" : {
				"id" : "-1",
				"name" : "",
				"description" : ""
			}
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1454350178
}
Organization User
Expand
{
	"type" : "regular",
	"response" : [
		{
			"id" : "1",
			"status" : "0",
			"username" : "head",
			"ldapUsername" : "",
			"firstname" : "",
			"lastname" : "",
			"title" : "",
			"email" : "",
			"address" : "",
			"city" : "",
			"state" : "",
			"country" : "",
			"phone" : "",
			"fax" : "",
			"createdTime" : "1433519288",
			"modifiedTime" : "1453477493",
			"lastLogin" : "1454349916",
			"lastLoginIP" : "172.20.0.0",
			"mustChangePassword" : "false",
			"locked" : "false",
			"failedLogins" : "0",
			"authType" : "tns",
			"fingerprint" : null,
			"password" : "SET",
			"managedUsersGroups" : [
				{
					"id" : "-1",
					"name" : "All Groups",
					"description" : "All Groups"
				}
			],
			"managedObjectsGroups" : [
				{
					"id" : "-1",
					"name" : "All Groups",
					"description" : "All Groups"
				}
			],
			"preferences" : [
				{
					"name" : "timezone",
					"value" : "America/Nome",
					"tag" : "system"
				}
			],
			"canUse" : true,
			"canManage" : true,
			"role" : {
				"id" : "2",
				"name" : "Security Manager",
				"description" : "The Security Manager role has full access to all actions at the organization level. A Security Manager has the ability to create new groups and manage existing ones. A Security Manager can also define how users interact with other groups.\n\nThe ability to manage other users and their objects can be configured using group permissions on the Access tab of User add/edit. This includes viewing and stopping running scans and reports."
			},
			"responsibleAsset" : {
				"id" : "19",
				"name" : "Windows Hosts",
				"description" : "The operating system detected has Windows installed.\n\nThis will be helpful for those getting started with SecurityCenter."
			},
			"group" : {
				"id" : "0",
				"name" : "Full Access",
				"description" : "Full Access group"
			},
			"ldap" : {
				"id" : "-1",
				"name" : "",
				"description" : ""
			}
		},
		{
			"id" : "36",
			"status" : "0",
			"username" : "GroupA",
			"firstname" : "",
			"lastname" : "",
			"title" : "",
			"email" : "",
			"address" : "",
			"city" : "",
			"state" : "",
			"country" : "",
			"phone" : "",
			"fax" : "",
			"createdTime" : "1447966099",
			"modifiedTime" : "1453476062",
			"lastLogin" : "1449517376",
			"lastLoginIP" : "172.20.0.0",
			"mustChangePassword" : "false",
			"locked" : "false",
			"failedLogins" : "0",
			"authType" : "tns",
			"fingerprint" : null,
			"password" : "SET",
			"managedUsersGroups" : [
				{
					"id" : "-1",
					"name" : "All Groups",
					"description" : "All Groups"
				}
			],
			"managedObjectsGroups" : [
				{
					"id" : "-1",
					"name" : "All Groups",
					"description" : "All Groups"
				}
			],
			"preferences" : [
				{
					"name" : "timezone",
					"value" : "America/Nome",
					"tag" : "system"
				}
			],
			"canUse" : true,
			"canManage" : true,
			"role" : {
				"id" : "2",
				"name" : "Security Manager",
				"description" : "The Security Manager role has full access to all actions at the organization level. A Security Manager has the ability to create new groups and manage existing ones. A Security Manager can also define how users interact with other groups.\n\nThe ability to manage other users and their objects can be configured using group permissions on the Access tab of User add/edit. This includes viewing and stopping running scans and reports."
			},
			"responsibleAsset" : {
				"id" : "14",
				"name" : "Systems that have been Scanned",
				"description" : "This asset uses the Scan Summary plugin to detect if a host has been scanned by Nessus. The Scan Summary plugin contains the list of tests conducted during the most resent scan."
			},
			"group" : {
				"id" : "2",
				"name" : "Group A",
				"description" : ""
			}
		},
		{
			"id" : "37",
			"status" : "0",
			"username" : "GroupB",
			"ldapUsername" : "",
			"firstname" : "",
			"lastname" : "",
			"title" : "",
			"email" : "",
			"address" : "",
			"city" : "",
			"state" : "",
			"country" : "",
			"phone" : "",
			"fax" : "",
			"createdTime" : "1447966134",
			"modifiedTime" : "1452788397",
			"lastLogin" : "1452528350",
			"lastLoginIP" : "172.20.0.0",
			"mustChangePassword" : "false",
			"locked" : "false",
			"failedLogins" : "0",
			"authType" : "tns",
			"fingerprint" : null,
			"password" : "SET",
			"managedUsersGroups" : [],
			"managedObjectsGroups" : [],
			"preferences" : [
				{
					"name" : "timezone",
					"value" : "America/Nome",
					"tag" : "system"
				}
			],
			"canUse" : true,
			"canManage" : true,
			"role" : {
				"id" : "2",
				"name" : "Security Manager",
				"description" : "The Security Manager role has full access to all actions at the organization level. A Security Manager has the ability to create new groups and manage existing ones. A Security Manager can also define how users interact with other groups.\n\nThe ability to manage other users and their objects can be configured using group permissions on the Access tab of User add/edit. This includes viewing and stopping running scans and reports."
			},
			"responsibleAsset" : {
				"id" : "16",
				"name" : "Linux Hosts",
				"description" : "The operating system detected has Linux installed."
			},
			"group" : {
				"id" : "3",
				"name" : "Group B",
				"description" : ""
			},
			"ldap" : {
				"id" : "-1",
				"name" : "",
				"description" : ""
			}
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1454350034
}

POST

Adds a User. Depending on your role, this resource will add the following:

  • An Administrator (by default if the session user has the Administrator Role) or a SecurityManager (if the session user is an Administrator and the optional field orgID is provided) into the provided organization.
  • A User within the Organization's context if the session user is not an Administrator and has permission to manage users in group.
Request Parameters
Expand
{
	"status" : <number> DEFAULT "0",
	"roleID" : <number>,
	"username" : <string>,
	"firstname" : <string> DEFAULT "",
	"lastname" : <string> DEFAULT "",
	"title" : <string> DEFAULT "",
	"email" : <string> DEFAULT "" (required to be present and valid if emailNotice is not empty and is not "none"),
	"address" : <string> DEFAULT "",
	"city" : <string> DEFAULT "",
	"state" : <string> DEFAULT "",
	"country" : <string> DEFAULT "",
	"phone" : <string> DEFAULT "",
	"fax" : <string> DEFAULT "",
	"locked" : <string> "false" | "true" DEFAULT "false",
	"authType" : <string> "ldap" | "legacy" | "saml" | "tns",
	"fingerprint" : <string> DEFAULT null,
	"emailNotice" :  <string> "both" | "id" | "none" | "password" DEFAULT "",
	"preferences" : [
		{
			"name" : <string>,
			"tag" : <string> DEFAULT "",
			"value" : <string>
		}...
	] DEFAULT [
		{
			"name" : "timezone",
			"tag" : "system",
			"value" : <string> (default timezone)
		}
	]
}

authType "ldap"

Note: The "ldapUsername" attribute will be set to mirror the "username" attribute.

...
	"mustChangePassword" : <string> "false" DEFAULT "false",
	"ldap" : {
		"id" : <string>
	}
...

authType "saml"

...
	"mustChangePassword" : <string> "false" DEFAULT "false"
...

authType not "ldap" or "saml"

...
	"password" : <string> (must meet the requirements for configuration setting, "PasswordMinLength"),
	"mustChangePassword" : <string> "false" | "true" DEFAULT "false"
...

Session user's role can manage group relationships or Session user role "1" (Administrator)

...
	"managedUsersGroups" : [
		{
			"id" : <number>
		}...
	],
	"managedObjectsGroups" : [
		{
			"id" : <number>
		}...
	]
...

Session user role "1" (Administrator)

...
	"orgID" : <number> DEFAULT "0" (adding another admin),
...

Session user role not "1" (Administrator)

...
	"groupID" : <number> (required to be a valid group ID whose users you can manage),
	"responsibleAssetID" : "-1" (NOT SET) | "0" (ALL ASSETS ACCESS) | <number> (number is required to be the id of a valid, usable, accessible asset) 
...

roleID not "1" (Administrator)

...
	"importReports" : <string> "true" | "false" DEFAULT "true" ,
	"importDashboards" : <string> "true" | "false" DEFAULT "true" ,
	"importARCs" : <string> "true" | "false" DEFAULT "true" ,

	"importDashboards" is "true"
	----------------------------
	"dashboardTemplate" : <string> (File path to template) DEFAULT <Default filepath>,

	"importARCs" is "true"
	----------------------
	"arcTemplate" : <string> (File path to template) DEFAULT <Default filepath>,
...
Example Response
Expand
{
	"type" : "regular",
	"response" : {
		"id" : "1",
		"status" : "0",
		"username" : "head",
		"ldapUsername" : "",
		"firstname" : "",
		"lastname" : "",
		"title" : "",
		"email" : "",
		"address" : "",
		"city" : "",
		"state" : "",
		"country" : "",
		"phone" : "",
		"fax" : "",
		"createdTime" : "1433519288",
		"modifiedTime" : "1453477493",
		"lastLogin" : "1454349916",
		"lastLoginIP" : "172.20.0.0",
		"mustChangePassword" : "false",
		"locked" : "false",
		"failedLogins" : "0",
		"authType" : "tns",
		"fingerprint" : null,
		"password" : "SET",
		"managedUsersGroups" : [
			{
				"id" : "-1",
				"name" : "All Groups",
				"description" : "All Groups"
			}
		],
		"managedObjectsGroups" : [
			{
				"id" : "-1",
				"name" : "All Groups",
				"description" : "All Groups"
			}
		],
		"preferences" : [
			{
				"name" : "timezone",
				"value" : "America/Nome",
				"tag" : "system"
			}
		],
		"canUse" : true,
		"canManage" : true,
		"role" : {
			"id" : "2",
			"name" : "Security Manager",
			"description" : "The Security Manager role has full access to all actions at the organization level. A Security Manager has the ability to create new groups and manage existing ones. A Security Manager can also define how users interact with other groups.\n\nThe ability to manage other users and their objects can be configured using group permissions on the Access tab of User add/edit. This includes viewing and stopping running scans and reports."
		},
		"responsibleAsset" : {
			"id" : "19",
			"name" : "Windows Hosts",
			"description" : "The operating system detected has Windows installed.\n\nThis will be helpful for those getting started with SecurityCenter."
		},
		"group" : {
			"id" : "0",
			"name" : "Full Access",
			"description" : "Full Access group"
		},
		"ldap" : {
			"id" : -1,
			"name" : "",
			"description" : ""
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1454350250
}

/user/{id}

Methods
GET

Gets the User associated with {id}. Depending on your role, this resource will return the following:

  • An Administrator (by default if the session user has the Administrator Role) or a SecurityManager (if the session user is an Administrator and the optional field orgID is provided) in the provided organization.
  • A User within the Organization's context if the session user is not an Administrator, depending on access and permissions
Fields Parameter
Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,...

Allowed Fields

*id
**username
**firstname
**lastname
**status
role
title
email
address
city
state
country
phone
fax
createdTime
modifiedTime
lastLogin
lastLoginIP
mustChangePassword
locked
failedLogins
authType
fingerprint
password
description
canUse
canManage
managedUsersGroups
managedObjectsGroups
preferences 

ldaps 

Session user is not role "1" (Administrator)

responsibleAsset
group

Legend

* = always comes back

** = comes back if fields list not specified on GET all

Request User Parameters

None

Example Response
Administrator
Expand
{
	"type" : "regular",
	"response" : {
		"id" : "1",
		"status" : "0",
		"username" : "admin",
		"ldapUsername" : "",
		"firstname" : "Admin",
		"lastname" : "User",
		"title" : "Application Administrator",
		"email" : "",
		"address" : "",
		"city" : "",
		"state" : "",
		"country" : "",
		"phone" : "",
		"fax" : "",
		"createdTime" : "1432921843",
		"modifiedTime" : "1453473716",
		"lastLogin" : "1454350174",
		"lastLoginIP" : "172.20.0.0",
		"mustChangePassword" : "false",
		"locked" : "false",
		"failedLogins" : "0",
		"authType" : "tns",
		"fingerprint" : null,
		"password" : "SET",
		"managedUsersGroups" : [],
		"managedObjectsGroups" : [],
		"preferences" : [
			{
				"name" : "timezone",
				"value" : "America/New_York",
				"tag" : ""
			}
		],
		"canUse" : true,
		"canManage" : true,
		"role" : {
			"id" : "1",
			"name" : "Administrator",
			"description" : "Role defining an administrator of the application"
		},
		"group" : {
			"id" : -1,
			"name" : "",
			"description" : ""
		},
		"ldap" : {
			"id" : -1,
			"name" : "",
			"description" : ""
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1454350376
}
Organization User
Expand
{
	"type" : "regular",
	"response" : {
		"id" : "1",
		"status" : "0",
		"username" : "head",
		"ldapUsername" : "",
		"firstname" : "",
		"lastname" : "",
		"title" : "",
		"email" : "",
		"address" : "",
		"city" : "",
		"state" : "",
		"country" : "",
		"phone" : "",
		"fax" : "",
		"createdTime" : "1433519288",
		"modifiedTime" : "1453477493",
		"lastLogin" : "1454349916",
		"lastLoginIP" : "172.20.0.0",
		"mustChangePassword" : "false",
		"locked" : "false",
		"failedLogins" : "0",
		"authType" : "tns",
		"fingerprint" : null,
		"password" : "SET",
		"managedUsersGroups" : [
			{
				"id" : "-1",
				"name" : "All Groups",
				"description" : "All Groups"
			}
		],
		"managedObjectsGroups" : [
			{
				"id" : "-1",
				"name" : "All Groups",
				"description" : "All Groups"
			}
		],
		"preferences" : [
			{
				"name" : "timezone",
				"value" : "America/Nome",
				"tag" : "system"
			}
		],
		"canUse" : true,
		"canManage" : true,
		"role" : {
			"id" : "2",
			"name" : "Security Manager",
			"description" : "The Security Manager role has full access to all actions at the organization level. A Security Manager has the ability to create new groups and manage existing ones. A Security Manager can also define how users interact with other groups.\n\nThe ability to manage other users and their objects can be configured using group permissions on the Access tab of User add/edit. This includes viewing and stopping running scans and reports."
		},
		"responsibleAsset" : {
			"id" : "19",
			"name" : "Windows Hosts",
			"description" : "The operating system detected has Windows installed.\n\nThis will be helpful for those getting started with SecurityCenter."
		},
		"group" : {
			"id" : "0",
			"name" : "Full Access",
			"description" : "Full Access group"
		},
		"ldap" : {
			"id" : -1,
			"name" : "",
			"description" : ""
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1454350250
}

PATCH

Edits the User associated with {id}, changing only the passed in fields. Depending on your role, this resource allow you to edit the following:

  • An Administrator (by default if the session user has the Administrator Role) or a SecurityManager (if the session user is an Administrator and the optional field orgID is provided) in the provided organization.
  • A User within the Organization's context if the session user is not an Administrator, depending on access and permissions

Cannot edit the current user using this endpoint.

Request Parameters

(All fields are optional)

See /user::POST for parameters.

Example Response
See /user/{id}::GET

DELETE

Deletes the User associated with {id}, depending on access and permissions. Depending on your role, this resource allows you to delete the following:

  • An Administrator (by default if the session user has the Administrator Role) or a SecurityManager (if the session user is an Administrator and the optional field orgID is provided) in the provided organization.
  • A User within the Organization's context if the session user is not an Administrator, depending on access and permissions

The objects owned by the user being deleted can be migrated to another user by passing in the optional migrateUserID parameter. Depending on your role, this resource allows you to migrate based on the following conditions:

  • If the session user has the Administrator Role, the Migrate User must be an Organization Security Manager in the Full Access Group and in the same Organization as the user being deleted
  • If the session user does not have the Administrator Role, you must be able to manage the objects of the Migrate User's group
Request Parameters
Expand

Session user is an Administrator

{
	"orgID" : <number> OPTIONAL,
	"migrateUserID": <number> OPTIONAL
}

Session user is not an Administrator

{
	"migrateUserID": <number> OPTIONAL
}
Example Response
Expand
{
	"type" : "regular",
	"response" : "",
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402436001
}