Tenable Access Control (Users) API
The Access Control (Users) API from Tenable — 10 operation(s) for access control (users).
OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Downloads About Access Control (Users) API
description: 'The Downloads API enables customers to access and download installation and update files for available Tenable products. You can use the API endpoints to list product pages, list downloads available for a specific product, and to download a file. The endpoints can also be used to determine and download the latest version of a file to facilitate the automation of an installation.
**Note:** The Tenable Downloads API uses a different server URL than the Tenable Vulnerability Management API:
`https://www.tenable.com/downloads/api/v2/pages`.
### Authentication
Like the Downloads website, certain files require authentication to download. When files have a `"requires_auth": true` attribute on the product list page, the Downloads API uses bearer token authentication and requires a valid token in the Authorization header to download the file:
```
Authorization: Bearer AbCdEf123456
```
To access or reset your authentication token, navigate to the [Authentication Token](https://www.tenable.com/downloads/api-docs) page.
Examples of product downloads that **do not** require authentication include Nessus and Nessus Agents.'
servers:
- url: https://www.tenable.com/downloads/api/v2
security:
- Bearer: []
tags:
- name: Access Control (Users)
x-displayName: Access Control (Users)
paths:
/users:
post:
summary: Create user
description: Creates a new user.<div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: users-create
tags:
- Access Control (Users)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: 'Specifies the login name for the user. A valid username must be in the format `name@domain`, where `domain` corresponds to a domain approved for your Tenable Vulnerability Management instance.
**Note:** During initial setup, Tenable configures approved domains for your Vulnerability Management instance. To add domains to your instance, contact Tenable Support.'
password:
type: string
description: Specifies the initial password for the user. Passwords must be at least 12 characters long and contain at least one uppercase letter, one lowercase letter, one number, and one special character symbol.
format: password
permissions:
type: integer
description: Specifies the user role as an integer value, as described in [User Roles](doc:roles#user-roles). If omitted, the system applies the Basic [16] user role by default.
format: int32
name:
type: string
description: Specifies the name of the user (for example, first and last name).
email:
type: string
description: 'Specifies the email address of the user. A valid email address must be in the format `name@domain`, where `domain` corresponds to a domain approved for your Tenable Vulnerability Management instance. Administrators can create users with an email address that has a domain outside of the approved domains.
This email address overrides the email address set in `username`. If omitted, the system uses the `username` value as the user''s email address.
**Note:** During initial setup, Tenable configures approved domains for your Vulnerability Management instance. To add domains to your instance, contact Tenable Support.'
required:
- username
- password
responses:
'200':
description: Returned if the user account was created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_user-object'
examples:
response:
value:
uuid: d748ab37-f2cf-461c-8648-a8328c0f483e
id: 2276957
user_name: user4@example.com
username: user4@example.com
email: user4@example.com
name: User Four
type: local
container_uuid: f8973c82-01a7-4aee-9754-4a61e3b3e70e
permissions: 32
login_fail_count: 0
login_fail_total: 0
enabled: true
lockout: 0
uuid_id: d748ab37-f2cf-461c-8648-a8328c0f483e
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to create a user.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- Access_Control_Users_cloud: []
get:
summary: List users
description: Returns a list of users.<div class="perms-callout">Requires the Basic [16] user role. If the requesting user has the Administrator [64] user role, Tenable Vulnerability Management returns all attributes for individual user details. Otherwise, user details include only the `uuid`, `id`, `username`, and `email` attributes. See [Roles](doc:roles).</div>
operationId: users-list
tags:
- Access Control (Users)
parameters:
- description: Specifies whether to include role-based access control (RBAC) role information in the response. If `true`, the system includes an `rbac_roles` array for each user containing the name and UUID of their assigned role. If omitted, the system uses the default value of `false`.
required: false
name: withRoles
in: query
schema:
type: boolean
default: false
responses:
'200':
description: Returned if the list of users was retrieved successfully.
content:
application/json:
schema:
type: object
description: An object containing an array of user objects.
properties:
users:
$ref: '#/components/schemas/Access_Control_Users_users'
examples:
response:
value:
users:
- uuid: 0d67d2fa-558c-4f89-b506-41b4b73101e1
id: 2247978
user_name: admin@example.com
username: admin@example.com
email: admin@example.com
name: Admin User
type: local
permissions: 64
rbac_roles:
- name: Administrator
uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
ui_permitted: true
ui_saml_only: false
api_permitted: true
last_login_attempt: 1641369870871
login_fail_count: 0
login_fail_total: 5
last_apikey_access: 1782787386952
enabled: true
undeletable: true
group_uuids:
- f3cd0bb2-cabb-4825-9d0c-49c77fe5fba7
- 00000000-0000-0000-0000-000000000000
lockout: 0
preferences:
enableExplore: 'true'
defaultApp: 'null'
enableWebAppWorkbench: 'false'
pinnedExposureInitiatives: '[]'
enableAssetWorkbench: 'false'
enableVMWorkbench: 'false'
enableExploreV2: 'false'
tenableGridState: 'null'
container_uuid: f8973c82-01a7-4aee-9754-4a61e3b3e70e
lastlogin: 1727938102779
uuid_id: 0d67d2fa-558c-4f89-b506-41b4b73101e1
- uuid: 1eddf745-7f6b-440a-90c6-df88efe2cf77
id: 2276956
user_name: user2@example.com
username: user2@example.com
email: user2@example.com
name: User Two
type: local
permissions: 40
rbac_roles:
- name: Scan Manager
uuid: b2c3d4e5-f6a7-8901-bcde-f12345678901
ui_permitted: true
ui_saml_only: false
api_permitted: true
last_login_attempt: 1584354906000
login_fail_count: 0
login_fail_total: 1
enabled: false
undeletable: false
group_uuids:
- 2d5c70da-b177-43ed-8325-a25a846c8977
- 00000000-0000-0000-0000-000000000000
lockout: 0
preferences:
enableExplore: 'true'
defaultApp: 'null'
enableWebAppWorkbench: 'false'
pinnedExposureInitiatives: '[]'
enableAssetWorkbench: 'false'
enableVMWorkbench: 'false'
enableExploreV2: 'false'
tenableGridState: 'null'
container_uuid: f8973c82-01a7-4aee-9754-4a61e3b3e70e
uuid_id: 1eddf745-7f6b-440a-90c6-df88efe2cf77
- uuid: d748ab37-f2cf-461c-8648-a8328c0f483e
id: 2347290
user_name: user3@example.com
username: user3@example.com
email: user3@example.com
type: local
permissions: 16
rbac_roles:
- name: Custom Role
uuid: c3d4e5f6-a7b8-9012-cdef-234567890abc
ui_permitted: true
ui_saml_only: false
api_permitted: true
login_fail_count: 0
login_fail_total: 0
enabled: true
undeletable: false
group_uuids:
- 00000000-0000-0000-0000-000000000000
lockout: 0
preferences:
enableExplore: 'true'
defaultApp: 'null'
enableWebAppWorkbench: 'false'
pinnedExposureInitiatives: '[]'
enableAssetWorkbench: 'false'
enableVMWorkbench: 'false'
enableExploreV2: 'false'
tenableGridState: 'null'
container_uuid: f8973c82-01a7-4aee-9754-4a61e3b3e70e
lastlogin: 1763122889995
uuid_id: d748ab37-f2cf-461c-8648-a8328c0f483e
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to view the list of users.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- Access_Control_Users_cloud: []
/users/{user_id}:
get:
summary: Get user details
description: Returns details for a specific user.<div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: users-details
tags:
- Access Control (Users)
parameters:
- description: Specifies the UUID (`uuid`) or unique ID (`id`) of the user.
required: true
name: user_id
in: path
schema:
type: string
format: uuid
responses:
'200':
description: Returned if the user details were retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_user-object'
examples:
response:
value:
uuid: 60f73e4f-8983-41c2-a13c-39074cbb6229
id: 2247978
user_name: user@example.com
username: user@example.com
email: user@example.com
name: User One
type: local
permissions: 64
last_login_attempt: 1641369870871
login_fail_count: 0
login_fail_total: 5
last_apikey_access: 1782787386952
enabled: true
undeletable: true
group_uuids:
- f3cd0bb2-cabb-4825-9d0c-49c77fe5fba7
- 00000000-0000-0000-0000-000000000000
lockout: 0
preferences:
enableExplore: 'true'
defaultApp: 'null'
enableWebAppWorkbench: 'false'
pinnedExposureInitiatives: '[]'
tenableGridState: '{"Settings_User_Group_Users":{"columns":{"user_name":{"hide":false,"sort":null,"sortIndex":null,"order":1},"name":{"hide":false,"sort":null,"sortIndex":null,"order":2},"twoFactor":{"hide":false,"sort":null,"sortIndex":null,"order":3},"lastlogin":{"hide":false,"sort":null,"sortIndex":null,"order":4},"last_login_attempt":{"hide":false,"sort":null,"sortIndex":null,"order":5},"login_fail_total":{"hide":false,"sort":null,"sortIndex":null,"order":6},"last_apikey_access":{"hide":false,"sort":null,"sortIndex":null,"order":7},"role":{"hide":false,"sort":null,"sortIndex":null,"order":8}}}}'
enableAssetWorkbench: 'false'
enableVMWorkbench: 'false'
enableExploreV2: 'false'
container_uuid: 270f77d7-3b5b-478c-ac06-be827c00753e
lastlogin: 1727938102779
uuid_id: 60f73e4f-8983-41c2-a13c-39074cbb6229
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to view the user details.
'404':
description: Returned if Tenable Vulnerability Management cannot find the specified user.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- Access_Control_Users_cloud: []
put:
summary: Update user
description: Updates an existing user account.<div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: users-edit
tags:
- Access Control (Users)
parameters:
- description: Specifies the UUID (`uuid`) or unique ID (`id`) of the user.
required: true
name: user_id
in: path
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
permissions:
type: integer
description: Specifies the user role as an integer value, as described in [User Roles](doc:roles#user-roles).
format: int32
name:
type: string
description: Specifies the name of the user (for example, first and last name).
email:
type: string
description: 'Specifies the email address of the user. A valid email address must be in the format `name@domain`, where `domain` corresponds to a domain approved for your Tenable Vulnerability Management instance. However, a user can update their own `email` property value to have an unapproved domain if an administrator has already approved the domain for that particular user.
This email address overrides the email address set in `username`. If omitted, the system uses the `username` value as the user''s email address.
**Note:** During initial setup, Tenable configures approved domains for your Vulnerability Management instance. To add domains to your instance, contact Tenable Support.'
enabled:
type: boolean
description: Specifies whether the user's account is enabled (`true`) or disabled (`false`).
responses:
'200':
description: Returned if the user was updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_user-object'
examples:
response:
value:
uuid: 1eddf745-7f6b-440a-90c6-df88efe2cf77
id: 4
user_name: user3@example.com
username: user3@example.com
email: user3@example.com
name: Test User
type: local
container_uuid: f8973c82-01a7-4aee-9754-4a61e3b3e70e
permissions: 32
login_fail_count: 0
login_fail_total: 0
enabled: false
lockout: 0
uuid_id: 1eddf745-7f6b-440a-90c6-df88efe2cf77
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to update a user.
'404':
description: Returned if Tenable Vulnerability Management cannot find the specified user.
'409':
description: Returned if you attempt to change your own account's enabled or disabled status.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- Access_Control_Users_cloud: []
delete:
summary: Delete user
description: Deletes a user.<div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: users-delete
tags:
- Access Control (Users)
parameters:
- description: The unique identifier (UUID) of the user to delete.
required: true
name: user_id
in: path
schema:
type: string
format: uuid
- description: 'Specifies the unique identifier (UUID) of the user to assign the deleted user''s objects to.
**Note:** Web App Scanning scans created by the deleted user are not automatically reassigned. Reassign WAS scans manually before deleting the user.'
name: successor_user_uuid
in: query
schema:
type: string
format: uuid
responses:
'200':
description: Returned if the user was deleted successfully.
content:
application/json:
schema: {}
examples:
response:
value: {}
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to delete the specified user.
'404':
description: Returned if Tenable Vulnerability Management cannot find the specified user.
'409':
description: Returned if you attempt to delete your own account.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- Access_Control_Users_cloud: []
/access-control/v1/users/{user_uuid}/roles:
get:
summary: Get user role
description: Returns the user role assigned to the specified user. <div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: access-control-users-role-list
tags:
- Access Control (Users)
parameters:
- description: Specifies the unique identifier (UUID) of the user whose role you want to retrieve.
required: true
name: user_uuid
in: path
schema:
type: string
format: uuid
responses:
'200':
description: Returned if the role for the specified user was retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_Object-User-Role'
examples:
response:
value:
container_uuid: 9b42306b-3ebb-451d-a250-0a1985509880
user_uuid: e02cad91-e3a6-4608-9145-7d4ece06e928
role_uuids:
- 7a26f80f-732c-4a2e-b962-d1d9b9511030
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to retrieve the user's role.
'404':
description: Returned if Tenable Vulnerability Management cannot find the specified user.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- Access_Control_Users_cloud: []
put:
summary: Change user role
description: Changes the role for the specified user. <div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: access-control-users-role-update
tags:
- Access Control (Users)
parameters:
- description: Specifies the unique identifier (UUID) of the user whose role you want to change.
required: true
name: user_uuid
in: path
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
role_uuids:
description: 'Specifies the unique identifier (UUID) of the role to assign to the user.
**Note:** Although `role_uuids` is defined as an array, you can only provide one role UUID.'
type: array
minItems: 1
maxItems: 1
items:
type: string
format: uuid
required:
- role_uuids
responses:
'200':
description: Returned if the user role was changed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_Object-User-Role'
examples:
response:
value:
container_uuid: 9b42306b-3ebb-451d-a250-0a1985509880
user_uuid: e02cad91-e3a6-4608-9145-7d4ece06e928
role_uuids:
- 7a26f80f-732c-4a2e-b962-d1d9b9511030
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Users_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to change the user's role.
'404':
description: Returned if Tenable Vulnerability Management cannot find the specified user.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tenable/refs/heads/main/openapi/tenable-access-control-users-api-openapi.yml