Tenable Access Groups v2 API
The Access Groups v2 API from Tenable — 4 operation(s) for access groups v2.
OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Downloads About Access Groups v2 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 Groups v2
x-displayName: Access Groups v2
paths:
/v2/access-groups:
post:
summary: Create access group
description: 'Creates an access group.
**Caution:** Access groups were deprecated in Tenable Vulnerability Management on February 4th, 2022. Tenable recommends that customers use [access control](ref:io-v3-access-control-permission-create) instead to manage user and group access to resources in Tenable Vulnerability Management. Please update any existing integrations that your organization has. For more information about access control, see [Access Control](https://docs.tenable.com/vulnerability-management/Content/Settings/access-control/AccessControl.htm) in the Tenable Vulnerability Management User Guide. <div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>'
operationId: io-v2-access-groups-create
deprecated: true
tags:
- Access Groups v2
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: "The name of the access group you want to create. This name must be: \n* Unique within your Tenable Vulnerability Management instance. \n* A maximum of 255 characters. \n* Alphanumeric, but can include limited special characters (underscore, dash, parenthesis, brackets, colon). \n \n**Note:** You can add a maximum of 5,000 access groups to an individual container."
type: string
access_group_type:
description: "The type of access group. It can be one of three possible types: \n * MANAGE_ASSETS—Users in this access group can view the asset records created during previous scans and scan the associated targets for those assets.\n * SCAN_TARGETS—Users in this access group can scan targets associated with the access group and view the results of those scans. Targets may be associated with existing assets.\n * ALL—This access group type is only applicable to the default system-generated \"All Assets\" access group that contains all assets in your organization. This group is referred to as the \"All Assets\" group in the user interface. By default, Tenable Vulnerability Management grants all users in this access group both CAN VIEW and CAN SCAN permissions."
type: string
enum:
- MANAGE_ASSETS
- SCAN_TARGETS
- ALL
all_users:
description: "Specifies whether assets in the access group can be viewed by all or only some users in your organization: \n* If `true`, all users in your organization have Can View access to the assets defined in the rules parameter. Tenable Vulnerability Management ignores any principal parameters in your request. \n* If `false`, only specified users have Can View access to the assets defined in the rules parameter. You define which users or user groups have access in the principals parameter of the request. \n \nIf you omit this parameter, Tenable Vulnerability Management sets the parameter to `false` by default."
type: boolean
all_assets:
description: This parameter must always be `false` or omitted from create requests to specify that the access group is a user-created group. If you submit a create request with this parameter set to `true`, the create request fails.
type: boolean
principals:
items:
$ref: '#/components/schemas/access-groups_v2_v2-AccessGroupPrincipal'
description: "An array of principals. Each principal represents a user or user group assigned to the access group. You cannot add an access group as a principal to another access group. \n \nTenable Vulnerability Management handles data in this array based on the all\\_users parameter of the request: \n* If all\\_users is `true`, Tenable Vulnerability Management ignores any principal data in the request. You can omit this parameter from the request. \n* If all\\_users is `false`, Tenable Vulnerability Management adds the principal data to the access group."
type: array
rules:
items:
$ref: '#/components/schemas/access-groups_v2_v2-AssetRule'
description: 'An array of asset rules. Tenable Vulnerability Management uses these rules to assign assets to the access group. You can specify a maximum of 1,000 rules for an individual access group. If you specify multiple rules for an access group, Tenable Vulnerability Management assigns an asset to the access group if the asset matches any of the rules. You can only add rules to access groups if the `all_assets` parameter is set to `false`.
**Note:** When configuring rules for an `access_group_type` of `SCAN_TARGETS`, the asset attribute type (`rules.type`) must match the target format used in the related scan. For example, if a `SCAN_TARGETS` type access group rule filters on the FQDN/Hostname attribute, the related scan succeeds if the scan target is specified in FQDN or hostname format, but fails if the scan target is specified in IPv4 address format.'
type: array
required:
- name
responses:
'200':
description: Returned if an access group was created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/access-groups_v2_v2-AccessGroup'
examples:
response:
value:
container_uuid: 5c910460-38cc-4edb-bda4-49b148a1ce93
created_at: '2020-05-03T17:26:59.465Z'
updated_at: '2020-05-03T17:26:59.465Z'
id: 7eed61fd-3985-4d1b-8b22-dfc466b5b8da
name: Test Group
all_assets: false
version: 1
status: PROCESSING
access_group_type: MANAGE_ASSETS
rules:
- type: fqdn
operator: eq
terms:
- example.com
principals:
- type: all_users
principal_id: 00000000-0000-0000-0000-000000000000
principal_name: All Users
permissions:
- CAN_VIEW
- type: user
principal_id: 3d5df50a-4de8-4b0e-9496-54a19a76ddcc
principal_name: user1@example.com
permissions:
- CAN_VIEW
- CAN_SCAN
created_by_uuid: 2460c1d6-0bfb-41e1-93b4-67fffcd9b0e5
updated_by_uuid: 2460c1d6-0bfb-41e1-93b4-67fffcd9b0e5
updated_by_name: admin@example.com
created_by_name: admin@example.com
processing_percent_complete: 0
'400':
description: "Returned if Tenable Vulnerability Management encountered any of the following error conditions:\n - max_entries—your request exceeds the maximum number of 5,000 access groups.\n - duplicate—an access group with the name you specified already exists.\n - protected—you attempted to set the all_assets parameter to `true`, and you cannot create the system-provided access group, All Assets."
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/access-groups_v2_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to create access groups.
'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-groups_v2_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-groups_v2_cloud: []
get:
summary: List access groups
description: 'Lists access groups without associated rules.
**Caution:** Access groups were deprecated in Tenable Vulnerability Management on February 4th, 2022. Tenable recommends that customers use [access control](ref:io-v3-access-control-permission-create) instead to manage user and group access to resources in Tenable Vulnerability Management. Please update any existing integrations that your organization has. For more information about access control, see [Access Control](https://docs.tenable.com/vulnerability-management/Content/Settings/access-control/AccessControl.htm) in the Tenable Vulnerability Management User Guide. <div class="perms-callout">Requires the Basic [16] user role to list access groups to which you are assigned. Requires the Administrator [64] user role to list all access groups for your organization. See [Roles](doc:roles).</div>'
operationId: io-v2-access-groups-list
deprecated: true
tags:
- Access Groups v2
parameters:
- description: 'A filter condition in the following format: `field:operator:value`. For a list of possible fields and operators, use the [GET /v2/access-groups/filters](ref:io-v2-access-groups-list-filters) endpoint. You can specify multiple `f` parameters, separated by ampersand (&) characters. If you specify multiple `f` parameters, use the `ft` parameter to specify how Tenable Vulnerability Management applies the multiple filter conditions.'
name: f
in: query
schema:
type: string
- description: If multiple `f` parameters are present, specifies whether Tenable Vulnerability Management applies `AND` or `OR` to conditions. Supported values are `and` and `or`. If you omit this parameter when using multiple `f` parameters, Tenable Vulnerability Management applies `AND` by default.
name: ft
in: query
schema:
type: string
- description: The search value that Tenable Vulnerability Management applies across the wildcard fields. Wildcard fields are specified in the `wf` parameter.
name: w
in: query
schema:
type: string
- description: A comma-separated list of fields where Tenable Vulnerability Management applies the search value specified in the `w` parameter. For a list of supported wildcard fields, use the [GET /v2/access-groups/filters](ref:io-v2-access-groups-list-filters) endpoint.
name: wf
in: query
schema:
type: string
- description: Specifies whether or not to include the `rules` and `principals` objects in the response. Tenable Vulnerability Management defaults to `false` if this parameter is omitted.
name: fullypopulateresponse
in: query
schema:
type: boolean
- description: The number of records to retrieve.
name: limit
in: query
schema:
type: integer
format: int32
- description: The starting record to retrieve. If this parameter is omitted, Tenable Vulnerability Management uses the default value of `0`.
name: offset
in: query
schema:
type: integer
format: int32
- description: 'The field you want to use to sort the results by along with the sort order. The field is specified first, followed by a colon, and the order is specified second (`asc` or `desc`). For example, `name:desc` would sort results by the `name` field in descending order.
If you specify multiple fields, the fields must be separated by commas. For example, `name:desc,created_at:asc` would first sort results by the `name` field in descending order and then by the `created_at` field in ascending order.
For a list of supported sort fields, use the [GET /v2/access-groups/filters](ref:io-v2-access-groups-list-filters) endpoint.'
name: sort
in: query
schema:
type: string
responses:
'200':
description: Returns a list of access groups that you have permission to view.
content:
application/json:
schema:
type: object
properties:
access_groups:
$ref: '#/components/schemas/access-groups_v2_v2-AccessGroup'
pagination:
$ref: '#/components/schemas/access-groups_v2_PaginationResponse'
examples:
response:
value:
access_groups:
- container_uuid: 5c910460-38cc-4edb-bda4-49b148a1ce93
created_at: '2018-10-31T13:18:29.185Z'
updated_at: '2020-04-09T06:48:22.024Z'
id: b52b489a-1c49-487d-aa8b-37ff1728ece8
name: All Assets
all_assets: true
version: 5
status: COMPLETED
access_group_type: ALL
principals:
- type: all_users
principal_id: 00000000-0000-0000-0000-000000000000
principal_name: All Users
permissions:
- CAN_SCAN
created_by_name: system
processing_percent_complete: 100
- container_uuid: 5c910460-38cc-4edb-bda4-49b148a1ce93
created_at: '2018-11-27T21:17:18.883Z'
updated_at: '2018-11-27T22:12:02.414Z'
id: 3e8cf339-2677-4322-bb59-d83ec93df93a
name: Western Region
all_assets: false
version: 2
status: COMPLETED
access_group_type: MANAGE_ASSETS
principals:
- type: all_users
principal_id: 00000000-0000-0000-0000-000000000000
principal_name: All Users
permissions: []
- type: user
principal_id: ccbca292-4095-4110-ae67-9556a4dfe8ad
principal_name: user1@example.com
permissions:
- CAN_VIEW
- type: user
principal_id: ed1bbdbf-8473-4ded-9abd-a3bce5e4df52
principal_name: user2@example.com
permissions:
- CAN_VIEW
created_by_uuid: a9d67a35-42de-4566-942b-e502d1c662e4
updated_by_uuid: a9d67a35-42de-4566-942b-e502d1c662e4
updated_by_name: user1@example.com
created_by_name: user1@example.com
processing_percent_complete: 100
- container_uuid: 5c910460-38cc-4edb-bda4-49b148a1ce93
created_at: '2019-05-31T20:11:14.122Z'
updated_at: '2019-05-31T20:11:14.122Z'
id: a419d8ed-58fb-45be-a4cc-b0ea17c7955a
name: networks-uuid-test
all_assets: false
version: 1
status: COMPLETED
access_group_type: MANAGE_ASSETS
principals:
- type: all_users
principal_id: 00000000-0000-0000-0000-000000000000
principal_name: All Users
permissions:
- CAN_VIEW
created_by_uuid: 72be80e1-6808-4097-8008-8c3aa0fa1242
updated_by_uuid: 72be80e1-6808-4097-8008-8c3aa0fa1242
updated_by_name: user1@example.com
created_by_name: user1@example.com
processing_percent_complete: 100
pagination:
offset: 0
total: 17
sort:
- name: allAssets
order: desc
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/access-groups_v2_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to view access groups.
'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-groups_v2_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-groups_v2_cloud: []
/v2/access-groups/{id}:
put:
summary: Update access group
description: 'Modifies an access group. This method overwrites the existing data.
**Caution:** Access groups were deprecated in Tenable Vulnerability Management on February 4th, 2022. Tenable recommends that customers use [access control](ref:io-v3-access-control-permission-create) instead to manage user and group access to resources in Tenable Vulnerability Management. Please update any existing integrations that your organization has. For more information about access control, see [Access Control](https://docs.tenable.com/vulnerability-management/Content/Settings/access-control/AccessControl.htm) in the Tenable Vulnerability Management User Guide. <div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>'
operationId: io-v2-access-groups-edit
deprecated: true
tags:
- Access Groups v2
parameters:
- description: The UUID for the access group you want to modify.
required: true
name: id
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: The name of the access group you want to modify.
type: string
access_group_type:
description: "The type of access group. It can be one of three possible types: \n * MANAGE_ASSETS—Users in this access group can view the asset records created during previous scans and scan the associated targets for those assets.\n * SCAN_TARGETS—Users in this access group can scan targets associated with the access group and view the results of those scans. Targets may be associated with existing assets.\n * ALL—This access group type is only applicable to the default system-generated \"All Assets\" access group that contains all assets in your organization. This group is referred to as the \"All Assets\" group in the user interface. By default, Tenable Vulnerability Management grants all users in this access group both CAN VIEW and CAN SCAN permissions."
type: string
enum:
- MANAGE_ASSETS
- SCAN_TARGETS
- ALL
all_users:
description: "Specifies whether assets in the access group can be viewed by all or only some users in your organization: \n* If `true`, all users in your organization have Can View access to the assets defined in the rules parameter. Tenable Vulnerability Management ignores any principal parameters in your request. \n* If `false`, only specified users have Can View access to the assets defined in the rules parameter. You define which users or user groups have access in the principals parameter of the request. \n \nIf you omit this parameter, Tenable Vulnerability Management sets the parameter to `false` by default."
type: boolean
all_assets:
description: "Specifies whether the access group you want to modify is the All Assets group or a user-defined group: \n* If you want to refine membership in the All Assets access group (the only change you can make to the All Assets group), this parameter must be `true`. Tenable Vulnerability Management ignores any rules parameters in your request, but overwrrites existing principals parameters with those in the request based on the all\\_users and principals parameters in the request. \n* If you want to modify a user-defined access group, this parameter must be `false`. Tenable Vulnerability Management overwrites the existing rules parameters with the rules parameters you specify in this request, and overwrites existing principals parameters based on the all\\_users and principals parameters in the request."
type: boolean
principals:
items:
$ref: '#/components/schemas/access-groups_v2_v2-AccessGroupPrincipal'
description: An array of principals. Each principal represents a user or user group assigned to the access group. You cannot add an access group as a principal to another access group.
type: array
rules:
items:
$ref: '#/components/schemas/access-groups_v2_v2-AssetRule'
description: 'An array of asset rules. Tenable Vulnerability Management uses these rules to assign assets to the access group. You can specify a maximum of 1,000 rules for an individual access group. If you specify multiple rules for an access group, Tenable Vulnerability Management assigns an asset to the access group if the asset matches any of the rules. You can only add rules to access groups if the `all_assets` parameter is set to `false`.
**Note:** When configuring rules for an `access_group_type` of `SCAN_TARGETS`, the asset attribute type (`rules.type`) must match the target format used in the related scan. For example, if a `SCAN_TARGETS` type access group rule filters on the FQDN/Hostname attribute, the related scan succeeds if the scan target is specified in FQDN or hostname format, but fails if the scan target is specified in IPv4 address format.'
type: array
responses:
'200':
description: Returned if the access group was updated successfully, or if a new access group was created because the system could not find an existing access group with the specified UUID.
content:
application/json:
schema:
$ref: '#/components/schemas/access-groups_v2_v2-AccessGroupDetails'
examples:
response:
value:
container_uuid: 5c910460-38cc-4edb-bda4-49b148a1ce93
created_at: '2020-05-03T17:26:59.465Z'
updated_at: '2020-05-03T17:29:03.197Z'
id: 7eed61fd-3985-4d1b-8b22-dfc466b5b8da
name: Test Group
all_assets: false
version: 2
status: PROCESSING
access_group_type: MANAGE_ASSETS
rules:
- type: fqdn
operator: eq
terms:
- example.com
principals:
- type: user
principal_id: 3d5df50a-4de8-4b0e-9496-54a19a76ddcc
principal_name: user2@example.com
permissions:
- CAN_VIEW
- CAN_SCAN
- type: all_users
principal_id: 00000000-0000-0000-0000-000000000000
principal_name: All Users
permissions:
- CAN_VIEW
created_by_uuid: 2460c1d6-0bfb-41e1-93b4-67fffcd9b0e5
updated_by_uuid: 2460c1d6-0bfb-41e1-93b4-67fffcd9b0e5
updated_by_name: admin@example.com
created_by_name: admin@example.com
processing_percent_complete: 0
'400':
description: "Returned if Tenable Vulnerability Management encountered any of the following error conditions:\n - incomplete—the body of your request did not include the required fields.\n - duplicate—an access group with the name you specified already exists.\n - protected—you attempted to update an access group where the `all_assets` parameter is set to `true`, and you cannot update the system-provided `All Assets` access group."
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/access-groups_v2_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have sufficient permissions to modify access groups.
'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-groups_v2_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-groups_v2_cloud: []
delete:
summary: Delete access group
description: 'Deletes an access group.
**Caution:** Access groups were deprecated in Tenable Vulnerability Management on February 4th, 2022. Tenable recommends that customers use [access control](ref:io-v3-access-control-permission-create) instead to manage user and group access to resources in Tenable Vulnerability Management. Please update any existing integrations that your organization has. For more information about access control, see [Access Control](https://docs.tenable.com/vulnerability-management/Content/Settings/access-control/AccessControl.htm) in the Tenable Vulnerability Management User Guide. <div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>'
operationId: io-v2-access-groups-delete
deprecated: true
tags:
- Access Groups v2
parameters:
- description: The UUID for the access group you want to delete.
required: true
name: id
in: path
schema:
type: string
responses:
'200':
description: Returned if the access group you specified was deleted successfully.
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/access-groups_v2_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have sufficient permissions to delete an access group.
'404':
description: Returned if Tenable Vulnerability Management could not find the access group you specified.
'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-groups_v2_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred
# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tenable/refs/heads/main/openapi/tenable-access-groups-v2-api-openapi.yml