Use this endpoint to programmatically manage service account roles (roles) and daily API allowances (quota_limits).

For roles and feature permissions, specify the roles array inside context_attributes. This replaces all existing roles of the service account with the ones provided in the request body.

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 service accounts is determined by your active license. You can inspect your enabled roles in the ROLES tab under My group in the web console, or query GET /v3/groups/{id}/relationships/service_accounts on an existing service account to inspect active roles strings.

For managing a service account's daily API cap, specify the allowed field within context_attributes -> quota_limits -> api_requests_daily.

Examples

Update roles and set daily API cap to 5,000 requests

import requests

group_id = "my_group_id"
service_account_id = f"{group_id}_secops_bot"
api_key = "YOUR_ADMIN_API_KEY"

url = f"https://www.virustotal.com/api/v3/groups/{group_id}/relationships/service_accounts"
headers = {
    "x-apikey": api_key,
    "Content-Type": "application/json"
}

payload = {
    "data": [
        {
            "type": "service_account",
            "id": service_account_id,
            "context_attributes": {
                "roles": [
                    "USER_ROLE_DTM_MEMBER",
                    "USER_ROLE_PRIVATE_SCANNING"
                ],
                "quota_limits": {
                    "api_requests_daily": {
                        "allowed": 5000
                    }
                }
            }
        }
    ]
}

response = requests.patch(url, json=payload, headers=headers)
print("Status Code:", response.status_code)
print("Response JSON:", response.json())

Expected Responses and Error Handling

Successful Update (HTTP 200 OK)

When the relationship is successfully updated, the API returns HTTP 200 OK with an empty response body ({}):

{}

Common Errors

• HTTP 400 Bad Request (Invalid Role Enum): Returned if an unrecognized or invalid role string is specified in roles. Check the exact enums supported by your license.
• HTTP 403 Forbidden (Insufficient Privileges): Returned if the x-apikey header belongs to a standard user rather than a Group Administrator (USER_ROLE_GROUP_ADMIN).
• HTTP 404 Not Found (Unknown Service Account ID): Returned if the id provided does not match an existing service account in the group. Remember that service account IDs always start with {group_id}_.