Tenable Access Control (Groups) API
The Access Control (Groups) API from Tenable — 4 operation(s) for access control (groups).
OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Downloads About Access Control (Groups) 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 (Groups)
x-displayName: Access Control (Groups)
paths:
/groups:
post:
summary: Create group
description: Creates a user group.<div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: groups-create
tags:
- Access Control (Groups)
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_Request-Group'
examples:
request:
value:
name: Engineering Team
managed_by_saml: true
responses:
'200':
description: Returned if the group was created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_Response-Group'
examples:
response:
value:
uuid: d4e5f6a7-b8c9-0123-def4-567890abcdef
managed_by_saml: true
name: Engineering Team
id: 1130088
container_uuid: c1d2e3f4-a5b6-7890-cdef-123456789abc
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse-Error'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to create groups. For more information, see [Roles](doc:roles) and [Permissions](doc:permissions).
'409':
description: Returned if a group with the specified name already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse-Error'
examples:
response:
value:
error: Duplicate Group name
'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_Groups_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_Groups_cloud: []
get:
summary: List groups
description: Lists all user groups for your container.<div class="perms-callout">Requires the Basic [16] user role. See [Roles](doc:roles).</div>
operationId: groups-list
tags:
- Access Control (Groups)
responses:
'200':
description: Returned if the list of groups was retrieved successfully.
content:
application/json:
schema:
type: object
properties:
groups:
type: array
description: An array of group objects.
items:
$ref: '#/components/schemas/Access_Control_Groups_Response-Group'
examples:
response:
value:
groups:
- uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: Security Team
user_count: 5
id: 1121822
container_uuid: c1d2e3f4-a5b6-7890-cdef-123456789abc
- uuid: b2c3d4e5-f6a7-8901-bcde-f12345678901
managed_by_saml: true
name: SAML Admins
user_count: 3
id: 1130086
container_uuid: c1d2e3f4-a5b6-7890-cdef-123456789abc
- uuid: 00000000-0000-0000-0000-000000000000
immutable: true
membership_fixed: true
name: All Users
user_count: 19
id: 0
container_uuid: c1d2e3f4-a5b6-7890-cdef-123456789abc
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to list groups. For more information, see [Roles](doc:roles) and [Permissions](doc:permissions).
'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_Groups_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_Groups_cloud: []
/groups/{group_uuid}:
put:
summary: Update group
description: Updates the specified user group.<div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: groups-edit
tags:
- Access Control (Groups)
parameters:
- description: Specifies the unique identifier (UUID) or integer ID of the group.
required: true
name: group_uuid
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_Request-Group'
examples:
request:
value:
name: Engineering
managed_by_saml: false
responses:
'200':
description: Returned if the specified group was updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_Response-Group'
examples:
response:
value:
uuid: d4e5f6a7-b8c9-0123-def4-567890abcdef
managed_by_saml: false
name: Engineering
user_count: 5
id: 1130088
container_uuid: c1d2e3f4-a5b6-7890-cdef-123456789abc
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse-Error'
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to update groups. For more information, see [Roles](doc:roles) and [Permissions](doc:permissions).
'404':
description: Returned if the specified group was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 404
error: Not Found
message: Not Found
'409':
description: Returned if a group with the specified name already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse-Error'
examples:
response:
value:
error: Duplicate Group name
'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_Groups_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_Groups_cloud: []
delete:
summary: Delete group
description: Deletes the specified user group. The group must have no users before it can be deleted.<div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: groups-delete
tags:
- Access Control (Groups)
parameters:
- description: Specifies the unique identifier (UUID) or integer ID of the group.
required: true
name: group_uuid
in: path
schema:
type: string
responses:
'200':
description: Returned if the group was deleted successfully.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse-Error'
examples:
response:
value:
error: Cannot delete Group[UUID=28836618-1db2-4b4c-b3d1-e8982ef8248d, accountUUID=8b42306b-3ebb-451d-a250-0a1985509880] that still has Users associated with it.
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to delete groups. For more information, see [Roles](doc:roles) and [Permissions](doc:permissions).
'404':
description: Returned if the specified group was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 404
error: Not Found
message: Not Found
'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_Groups_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_Groups_cloud: []
/groups/{group_uuid}/users:
get:
summary: List users in group
description: Lists the users in the specified group.<div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: groups-list-users
tags:
- Access Control (Groups)
parameters:
- description: Specifies the unique identifier (UUID) or integer ID of the group.
required: true
name: group_uuid
in: path
schema:
type: string
responses:
'200':
description: Returned if the list of users for the specified group was retrieved successfully.
content:
application/json:
schema:
type: object
properties:
users:
type: array
description: An array of user objects.
items:
$ref: '#/components/schemas/Access_Control_Groups_user-object'
examples:
response:
value:
users:
- uuid: e5f6a7b8-c9d0-1234-ef56-7890abcdef12
id: 2322321
user_name: user@example.com
username: user@example.com
email: user@example.com
name: User One
type: local
permissions: 64
login_fail_count: 0
login_fail_total: 0
last_apikey_access: 1764615703580
enabled: true
group_uuids:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
- 00000000-0000-0000-0000-000000000000
lockout: 0
preferences:
enableExplore: 'true'
defaultApp: 'null'
enableWebAppWorkbench: 'false'
tenableGridState: 'null'
enableAssetWorkbench: 'false'
enableVMWorkbench: 'false'
enableExploreV2: 'false'
pinnedExposureInitiatives: '[]'
container_uuid: c1d2e3f4-a5b6-7890-cdef-123456789abc
lastlogin: 1741206963401
uuid_id: e5f6a7b8-c9d0-1234-ef56-7890abcdef12
- uuid: f6a7b8c9-d0e1-2345-f678-90abcdef1234
id: 2354920
user_name: user2@example.com
username: user2@example.com
email: user2@example.com
name: User Two
type: local
permissions: 16
login_fail_count: 0
login_fail_total: 0
enabled: true
group_uuids:
- 00000000-0000-0000-0000-000000000000
lockout: 0
preferences:
enableExplore: 'true'
defaultApp: 'null'
enableExploreV2: 'false'
enableWebAppWorkbench: 'false'
pinnedExposureInitiatives: '[]'
tenableGridState: 'null'
enableAssetWorkbench: 'false'
enableVMWorkbench: 'false'
container_uuid: c1d2e3f4-a5b6-7890-cdef-123456789abc
uuid_id: f6a7b8c9-d0e1-2345-f678-90abcdef1234
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to list users in groups. For more information, see [Roles](doc:roles) and [Permissions](doc:permissions).
'404':
description: Returned if the specified group was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 404
error: Not Found
message: Not Found
'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_Groups_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_Groups_cloud: []
/groups/{group_uuid}/users/{user_uuid}:
post:
summary: Add user to group
description: Adds a user to the specified group.<div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: groups-add-user
tags:
- Access Control (Groups)
parameters:
- description: Specifies the unique identifier (UUID) or integer ID of the group.
required: true
name: group_uuid
in: path
schema:
type: string
- description: Specifies the unique identifier (UUID) or integer ID of the user.
required: true
name: user_uuid
in: path
schema:
type: string
responses:
'200':
description: Returned if the user was added to the group successfully.
content:
application/json:
schema:
type: object
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_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to add users to groups. For more information, see [Roles](doc:roles) and [Permissions](doc:permissions).
'404':
description: Returned if the specified group or user was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 404
error: Not Found
message: Not Found
'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_Groups_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_Groups_cloud: []
delete:
summary: Remove user from group
description: Removes a user from the specified group.<div class="perms-callout">Requires the Administrator [64] user role. See [Roles](doc:roles).</div>
operationId: groups-delete-user
tags:
- Access Control (Groups)
parameters:
- description: Specifies the unique identifier (UUID) or integer ID of the group.
required: true
name: group_uuid
in: path
schema:
type: string
- description: Specifies the unique identifier (UUID) or integer ID of the user.
required: true
name: user_uuid
in: path
schema:
type: string
responses:
'200':
description: Returned if the user was removed from the group successfully.
content:
application/json:
schema:
type: object
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_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 401
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to delete users from groups. For more information, see [Roles](doc:roles) and [Permissions](doc:permissions).
'404':
description: Returned if the specified group or user was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Access_Control_Groups_ErrorResponse'
examples:
response:
value:
statusCode: 404
error: Not Found
message: Not Found
'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_Groups_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_Groups_cloud: []
components:
schemas:
Access_Control_Groups_Request-Group:
type: object
properties:
name:
type: string
description: Specifies the name of the group.
managed_by_saml:
type: boolean
description: Specifies whether to allow users to be added to or removed from this group during SAML single sign-on (`true`) or to manage group membership independently of SAML (`false`).
required:
- name
Access_Control_Groups_Response-Group:
type: object
properties:
uuid:
type: string
format: uuid
description: The unique identifier (UUID) for the group.
name:
type: string
description: The name of the group.
id:
type: integer
description: The unique integer identifier of the group.
container_uuid:
type: string
format: uuid
description: The UUID of the container the group belongs to.
user_count:
type: integer
description: The number of users in the group. Only present on list and update responses.
managed_by_saml:
type: boolean
description: A flag indicating whether users can be added to or removed from this group during SAML single sign-on. Only present if SAML management is enabled for the group.
immutable:
type: boolean
description: A flag indicating the group cannot be modified. Only present on the default `All Users` group.
membership_fixed:
type: boolean
description: A flag indicating users cannot be added to or removed from this group. Only present on the default `All Users` group.
Access_Control_Groups_ErrorResponse-Error:
type: object
properties:
error:
type: string
description: A brief description of the error.
Access_Control_Groups_TwoFactor:
type: object
properties:
sms_phone:
type: string
description: The phone number used for two-factor authentication. The phone number begins with the `+` character and the country code. This field is required when sms_enabled is set to `true`.
sms_enabled:
type: integer
description: Indicates whether two-factor authentication is enabled (`1`) or disabled (`0`).
email_enabled:
type: integer
description: Indicates whether backup notification for two-factor authentication is enabled (`1`) or disabled (`0`). If enabled, Tenable Vulnerability Management sends the two-factor verification code via e-mail, as well as via the default SMS message.
Access_Control_Groups_user-object:
type: object
properties:
uuid:
type: string
description: The UUID of the user.
id:
type: integer
description: The unique ID of the user.
user_name:
type: string
description: The username for the user.
username:
type: string
description: The username for the user.
email:
type: string
description: The email address of the user. If this attribute is empty, Tenable Vulnerability Management uses the `username` value as the user's email address.
name:
type: string
description: The name of the user (for example, first and last name).
type:
type: string
description: The type of user. The only supported type is `local`.
permissions:
type: integer
description: The user permissions as described in [Permissions](doc:permissions).
format: int32
rbac_roles:
type: array
description: The role-based access control (RBAC) roles assigned to the user. This property is only present in the response when the `withRoles` query parameter is set to `true`. For more information, see [Roles](doc:roles).
items:
type: object
properties:
name:
type: string
description: The name of the role assigned to the user.
uuid:
type: string
format: uuid
description: The unique identifier (UUID) of the role assigned to the user.
ui_permitted:
type: boolean
description: Indicates whether the user is permitted to log
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tenable/refs/heads/main/openapi/tenable-access-control-groups-api-openapi.yml