Use this endpoint to manage users' group roles and feature permissions as well as users' daily API allowance.
For roles and feature permissions, the following operations are available in the request body:
roles: replaces all existing roles with the ones provided in the request.add_roles: appends new roles to the user. If a role already exists, it will be updated with the new configuration.remove_roles: revokes only the specific roles provided in the request.
The complete set of available RBAC role enum strings (USER_ROLE_*) across all Google Threat Intelligence products includes:
USER_ROLE_GROUP_ADMIN: Full administrative access to manage group users, settings, and quotas.USER_ROLE_DTM_ADMIN: Full administrative management over Digital Threat Monitoring assets and alerts.USER_ROLE_DTM_MEMBER: Standard read/write access to Digital Threat Monitoring alerts and brand mentions.USER_ROLE_ALERTS_ADMIN: Full management of My Landscape / Relevance System rules and alerts.USER_ROLE_ALERTS_MEMBER: Standard access to view and enrich Relevance System alerts in My Landscape.USER_ROLE_ASM_USER: Access Attack Surface Management (ASM) discoveries, assets, and issues.USER_ROLE_PRIVATE_SCANNING: Upload and scan files privately without sharing payloads or indexing publicly.USER_ROLE_FILE_DOWNLOADS: Download sample payloads from historical feeds and live hunts.USER_ROLE_FILE_UPLOADS: Submit standard files for public analysis and scanning.USER_ROLE_PRIVATE_FILE_UPLOADS: Submit files to private storage pools without public distribution.USER_ROLE_PRIVATE_FILE_DOWNLOADS: Download files exclusively from your organization's private storage pool.
Where to verify your organization's active roles: The exact subset of roles available to your group is determined by your active license. You can inspect your enabled roles in the ROLES tab under My group in the web console, or programmatically query an existing user object via GET /v3/groups/{id}/relationships/users to view active roles strings.
For managing users' daily API allowance, the allowed field must be specified within the context_attributes -> quota_limits -> api_requests_daily object, as shown in the example below.
Examples
Lower the user's daily API cap to 10.
import requests
group_id = "my_group_id"
user_id = "user_1"
api_key = "YOUR_ADMIN_API_KEY"
allowance = 10
url = f"https://www.virustotal.com/api/v3/groups/{group_id}/relationships/users"
headers = {
"x-apikey": api_key,
"content-type": "application/json"
}
payload = {
'data': [
{
'type': 'user',
'id': user_id,
'context_attributes': {
'quota_limits': {
'api_requests_daily': {
'allowed': allowance
}
}
}
}
]
}
res = requests.patch(url, json=payload, headers=headers)
print("Status Code:", res.status_code)
print("Response JSON:", res.json())Clear all individual settings and grant administrative privileges within the group to both user_1 and user_2.
import requests
group_id = "my_group_id"
user_id_1 = "user_1"
user_id_2 = "user_2"
api_key = "YOUR_ADMIN_API_KEY"
roles = ["USER_ROLE_GROUP_ADMIN"]
url = f"https://www.virustotal.com/api/v3/groups/{group_id}/relationships/users"
headers = {
"x-apikey": api_key,
"content-type": "application/json"
}
payload = {
'data': [
{
'type': 'user',
'id': user_id_1,
'context_attributes': {
'roles': roles
}
},
{
'type': 'user',
'id': user_id_2,
'context_attributes': {
'roles': roles
}
}
]
}
res = requests.patch(url, json=payload, headers=headers)
print("Status Code:", res.status_code)
print("Response JSON:", res.json())Downgrade the user's DTM privileges from administrative to standard access.
import requests
group_id = "my_group_id"
user_id = "user_1"
api_key = "YOUR_ADMIN_API_KEY"
roles = ["USER_ROLE_DTM_MEMBER"]
url = f"https://www.virustotal.com/api/v3/groups/{group_id}/relationships/users"
headers = {
"x-apikey": api_key,
"content-type": "application/json"
}
payload = {
'data': [
{
'type': 'user',
'id': user_id,
'context_attributes': {
'add_roles': roles
}
}
]
}
res = requests.patch(url, json=payload, headers=headers)
print("Status Code:", res.status_code)
print("Response JSON:", res.json())Revoke the user's access to DTM and ASM.
import requests
group_id = "my_group_id"
user_id = "user_1"
api_key = "YOUR_ADMIN_API_KEY"
roles = ["USER_ROLE_ASM_USER", "USER_ROLE_DTM_ADMIN", "USER_ROLE_DTM_MEMBER"]
url = f"https://www.virustotal.com/api/v3/groups/{group_id}/relationships/users"
headers = {
"x-apikey": api_key,
"content-type": "application/json"
}
payload = {
'data': [
{
'type': 'user',
'id': user_id,
'context_attributes': {
'remove_roles': roles
}
}
]
}
res = requests.patch(url, json=payload, headers=headers)
print("Status Code:", res.status_code)
print("Response JSON:", res.json())