VirusTotal’s premium users are categorized into two primary group roles: Users (standard users) and Admins (group administrators). Additionally, role-based access controls are applied to users for certain features and tools available across the platform.

This document outlines the enhanced privileges of group administrators, detailing the management actions available to them at both the organizational group and individual user levels.

General notions

All management actions restricted to administrators are accessible from the web interface under the My Group menu option, on the top right corner.

Group information

Here you can find the group’s preferences including two of the most important group level parameters, the group’s ID and the group's Token, which are required in multiple automation and object-sharing tasks.
Additional group related information is split in several tabs which allow management of different types of features. Please note that depending on the group's configuration and acquired services, the number of tabs available for each group can vary.

User information

Going down to the user level, they are listed in the USERS tab, where group administrators can easily filter shown group members by security settings and group role and also by typing the name or email address of the user of interest.

Additionally, by clicking on a user name, you automatically pivot to the user’s profile where user ID is shown next to the user's avatar. This ID is required in multiple automation tasks that are shown in next sections.

Service account information

Apart from users, a group could also have service accounts which are very useful for tasks automation since they are unaffected by people changes, as they are not tied to any specific individual and they don’t require an email address to be created. This makes them a more reliable and consistent way to grant access to automation resources than user accounts.
Service accounts are listed on the Service accounts section available on the USERS tab where you can check their IDs.

API notions

In addition to the web interface there is a set of API endpoints designed to automate most administrative tasks (more on this later). These endpoints are shown on the VT ENTERPRISE ADMINISTRATION section of the API v3 documentation - please note that NOT all of them require administrator privileges.
Their usage requires authentication/authorization through the admin's API key that can be found here (or on the top right corner of the web interface -> API key menu option).

Everything a VT Admin can do

As we discussed, almost every action in VT can be performed in 2 ways: via web interface and via API v3 requests. We grouped all actions reserved for administrator users in the following categories.

1. Group members management
2. Group management
3. Consumption
- 3.1. VirusTotal enterprise features consumption
  - 3.1.1. Getting current month group overall enterprise consumption
  - 3.1.2. Getting users individual enterprise consumption
- 3.2. VirusTotal API consumption
  - 3.2.1. Getting group overall API consumption
  - 3.2.2. Getting users individual API consumption
4. Audit Log

1. Group members management

1.1. Getting group members

1.1.1. Getting the list of users and service accounts

Web interface => On the My Group menu option -> USERS tab, the list of users is shown under the Group Members section, and the list of service accounts under the Service accounts section. All of them can be exported by administrators through the Export button in several file formats, as shown in the following image.

The result file will include the following information: username, first name, last name, email and type to identify whether it is a user account or a service account.

VirusTotal API => The endpoint /v3/groups/{id}/{relationship} returns the objects related to the group based on group’s ID (check group ID) and relationship which identifies the type of objects to request and whose values in this case are “users” and “service_accounts”.
Other endpoints provide the list of users and service accounts, but they don’t provide the same information as the already mentioned one: /v3/groups/{id}/relationships/users and /v3/groups/{id}/relationships/service_accounts.

1.2. Users management

1.2.1. Adding new user to the VT group

Web interface => From the My Group menu option -> USERS tab -> Add dropdown button -> User option, a group administrator is able to create or add new members to their group by entering a comma-separated list of email addresses and assigning them either Admin or User (standard access) roles via the corresponding checkboxes.

If a user is added to a group but doesn't yet have an account, they will be sent an email invitation to create one. Upon account creation, the user will be automatically added to the group. On the contrary, if the user already has an existing account, they will be automatically added to the group and receive a welcome email.

Please note that users can only belong to one group at a time. If a user is already a member of another group, they must be removed from it before they can be added to yours.

VirusTotal API => The /v3/groups/{id}/relationships/users endpoint allows administrators to add users to the group as common members. This endpoint requires the group ID (check group ID) as a parameter, and a list of user objects identified by their email addresses to convert in new group members as in the following example:

payload = {
  "data": [
    {"type":"user","id":"user_1_email_address"},
    {"type":"user","id":"user_2_email_address"}
  ]
}

There’s no specific endpoint for creating administrator members as in the web interface, although there’s a way of granting admin privileges to common users when needed. Check out the ‘Managing users privileges’ section.

1.2.2. Removing user from the VT group

Web interface => The list of users is given on the My Group menu option -> USERS tab -> Group Members section. Each user has a bin icon at the right, that allows administrators to remove it from the VT group, so that it is no longer a group member. Instead, it becomes a free user with limited access to VirusTotal’s products.

VirusTotal API => The /v3/groups/{id}/relationships/users/{user_id} endpoint removes a given user from a given group, based on their identifiers. (Check group ID) (Check user ID) When removing a user from the group, it becomes a free user with limited access to VirusTotal’s products.

1.2.3. Managing user privileges

Web interface => The list of users is given on the My Group menu option -> USERS tab -> Group Members section. Users' group role and features access privileges are displayed in the Roles column. Access levels for specific features and the group role are represented by color-coded symbols in light mode:

Blue: administrative access
Black: standard access
Gray: no access

While in dark mode the color-coded symbols are as follows:

Blue: administrative access
White: standard access
Gray: no access

Administrators can manage these settings individually via the pen (edit) button in the Roles column, or in bulk by selecting multiple users and clicking the Manage Roles button at the top of the Group Members section, as shown in the image below.

Individual Management: the edit form displays the user's current configuration, allowing for precise adjustments.
Bulk Management: no current settings are displayed. Any roles selected in the form will be applied to all highlighted users, and any roles left unselected will remain unchanged from their original state.

VirusTotal API => The /v3/groups/{id}/relationships/users endpoint allows to manage users roles and privileges based on their user IDs and the group ID parameter. (Check group ID)
On the other hand, the /v3/groups/{id}/relationships/administrators/{user_id} endpoint revokes admin privileges of a given user based on its ID and the group ID. (Check user ID) (Check group ID)

1.2.4. Managing user API allowance

Web interface => The list of users is given on the My Group menu option -> USERS tab -> Group Members section. Each of them has a pen icon that allows administrators to change the user’s Daily API cap that is shown next to the pen icon.

VirusTotal API => The /v3/users/{id} endpoint can be used to PATCH a VirusTotal user object based on its ID. (Check user ID) This endpoint also serves to change an user daily API cap as in the following example:

payload = {
  "data": {
    "attributes": {
      "quotas": {
        "api_requests_daily": {
          "allowed": 300
        }
      }
    },
    "type": "user"
  }
}

1.3. Service accounts management

1.3.1. Adding a new service account to the VT group

Web interface => Service accounts are very useful in automating enrichment and other automation tasks, since they are not tied to any specific individual.
From the My Group menu option -> USERS tab -> Add dropdown button -> Service Account option, administrators are able to create new service accounts.

On the opened form, administrators only have to specify the name or identifier that the new service account will receive, before saving the request.

VirusTotal API => Although creating new service accounts is a very occasional activity and you might not need to automate it because the web interface serves well for this purpose, the /v3/groups/{id}/relationships/service_accounts endpoint can be used as well. It only requires the group ID (check group ID) and a new service account object with the ID that it will receive as in the following example:

payload = {
  "data": [
    {"id": "vt_enrichment", "type": "service_account"}
  ]
}

1.3.2. Removing a service account from the VT group

Web interface => The list of service accounts is given on the My Group menu option -> USERS tab -> Service accounts section. Each of them has a bin icon at the right, that allows administrators to delete the specific service account.
Please make sure that you are not going to interfere with any integration with VT by removing service accounts whose API key is being used internally.

1.3.3. Getting a service accounts API key

Web interface => The list of service accounts is given on the My Group menu option -> USERS tab -> Service accounts section. Each of them has an icon for unhiding the API key and another icon for copying it to the clipboard. Only administrators are able to get the API key of a service account to use it on automation tasks such as IoCs enrichment.

VirusTotal API => Although checking service accounts API keys is a very occasional activity and you might not need to automate it because the web interface serves well to this purpose, the /v3/service_accounts/{id} endpoint can be used as well. It only requires the service account ID or name. (Check service account ID)

2. Group management

2.1. General settings

2.1.1. Editing organization name, domain name and avatar

Web interface => On the web platform, administrators can find 2 ways of modifying organization name and domain name.

The first one is on the My Group menu option -> GROUP PREFERENCES. By selecting the pen icon administrators are able to edit Organization and Domain name parameters.

The second way of editing this data is from the My Group menu option -> SETTINGS tab -> Group info section -> Organization and Domain name text boxes.

As for the group avatar, on the My Group menu option, at the top left is a Change avatar button that allows not only administrators but also common users to change group's avatar.

2.2. Security features

2.2.1. Editing all group members session timings

Web interface => On the My Group menu option -> SETTINGS tab -> Security controls section, administrators are able to define session maximum lifetime and inactivity time. Both of them are represented in seconds although they also show some default options by clicking on the input box.
When these times are exceeded, users are forced to re-authenticate.

2.2.2. Single Sign On - SSO

Web interface => On the My Group menu option -> SETTINGS tab -> Single sign-on section, administrators are able to configure the Identity provider for SSO. Through the dropdown option, administrators can enable one of the 3 SSO services already integrated or configure other preferred identity providers via Security Assertion Markup Language (SAML).
Please note that this only affects the authentication on the web platform. VirusTotal API authentication is not affected.

Already integrated identity provider services

If users have accounts in any of the 3 services (Google, GitHub, Microsoft), they can use those services to authenticate on our platform. For more information, refer to this document. Please note that users can always use one of these accounts without having to modify the My Group SSO configuration, but once configured, no one no longer will be able to authenticate on the platform via common credentials.

SAML

For configuring SAML administrators can check out these guide examples for Okta, Ping or Entra ID and replicate it to the preferred identity provider. The information needed to configure it is shown when selecting the Other (SAML) option in the Identity provider dropdown element.

Please note that for forcing users to only authenticate via SAML, a checkbox is provided. If this checkbox is not selected, users can use both methods of authentication: SAML and common credentials. We recommend allowing both authentication mechanisms during SAML configuration to avoid losing access to the platform in case of any misconfiguration.

Please note that you must manually update rotated certificates in the SAML settings on the platform.

OIDC

The information needed to configure it is shown when selecting the Other (OIDC) option in the Identity provider dropdown element.
Please note that for forcing users to only authenticate via OIDC, a checkbox is provided. If this checkbox is not selected, users can use both methods of authentication: OIDC and common credentials. We recommend allowing both authentication mechanisms during OIDC configuration to avoid losing access to the platform in case of any misconfiguration.

Adding new user to an existing VirusTotal group - automatically

Web interface => On My group menu option -> SETTINGS tab -> Group info section -> Auto add emails text box. Additionally, here group administrators can enable the below checkbox to be notified every time a new user is added to their group as a group member. This text box supports 2 types of inputs or conditions: complete email addresses and/or organization domain names regular expressions, with wildcards,([email protected], [email protected]), one entry per line.
When enabling this feature, new users whose email addresses meet one of the configured conditions and who are created through the group SSO sign-in link, are automatically added to the group, inheriting group's default configurations.

VirusTotal API => The /v3/groups/{id} endpoint can be used to PATCH a VirusTotal group object based on its group ID. (Check group ID) The parameter associated with the automatically adding users to groups feature is data->attributes->auto_add_users. This parameter is a list of regular expressions (*@company_domain) and complete email addresses that are going to be checked with every new user, and those meeting any entry will be automatically added to the group as a new member. When using this endpoint, don't forget to specify the object 'type': 'group' in the payload parameter as in the following example:

payload = {
  "data": {
    "type": "group",
    "attributes": {
      "auto_add_users":["*@google.com", "*@virustotal.com", "email_addres1", "email_address2"]
    }
  }
}

Please note that since this parameter is rarely edited and the web interface is more than enough to cover it, we highly recommend editing this parameter manually through the web interface.

2.3. Private Scanning settings

2.3.1. Editing PS retention period and storage region

Web interface => On the My Group menu option -> SETTINGS tab -> Private scanning section, group administrators can configure the default Retention period days of files submitted to Private Scanning, their Storage region during their lifetime in VirusTotal's database and also some analysis preferences such as detonating the sample in dynamic analysis sandboxes to be not just statically but also dynamically analyzed. For this, other configurations are available such as enabling internet access to allow external communications of the file and intercepting HTTP/TLS communications. Additionally, there's an option for enabling live interactions of analysts with the sandbox where the sample is detonated.

This configuration will be used by default, although users are able to configure these parameters for each file they are submitting to Private Scanning directly from the submission form.

2.4. Invoice settings

2.4.1. Getting invoice notifications

Web interface => On the My Group menu option -> SETTINGS tab -> Group info section -> Send invoices to text box, administrators can configure a list of email addresses to be notified of every new invoice.
Please note that this is available only if the organization is paying VirusTotal Enterprise via credit card.

Additionally, invoices can be accessed by administrators from the My Group menu option -> INVOICES tab.

3. Consumption

3.1. VirusTotal enterprise features consumption

3.1.1. Getting current month group overall enterprise consumption

Web interface => On the My Group menu option -> USAGE tab -> the Consumption current month section displays usage per VirusTotal feature relative to your monthly allowance. If any of the features is not available Exceeded consumption will be highlighted in red.

3.1.2. Getting users individual enterprise consumption

Web interface => On the My Group menu option -> USAGE tab, there are several sections providing a breakdown of the group’s monthly consumption by feature and user, displaying only those features with active usage:

Search consumption by user
Downloads consumption by user
Livehunt rules consumption by user
Retrohunt consumption by user
etc

3.2. VirusTotal API consumption

3.2.1 Getting group overall API consumption

Web interface => On the My Group menu option -> API tab, there's a section showing the Access level and API allowance assigned to the group as the Daily quota and the Request rate per minute.

There are 2 additional sections showing the group's overall API consumption: Consumption last 30 days breaks down the group's last 30 days API consumption by day, and Consumption by endpoint shows previous day consumption by endpoint. For more granular details please use the VirusTotal APIv3.

VirusTotal API => The /v3/groups/{id}/api_usage endpoint shows a group’s API usage broken down by day and endpoint, pointing out the endpoints that really consume API as well as those that do not (not_consuming_quota). The data available includes only the last 60 natural days and the required parameter is the group ID. (Check group ID) Additionally, you can specify the start day and last day parameters of the time range you want to track (yyyymmdd format).

3.2.2. Getting users individual API consumption

Web interface => On the My Group menu option -> API tab -> Consumption by user section shows previous day’s consumption by user. For more granular details please use the APIv3.

VirusTotal API => The /v3/users/{id}/api_usage endpoint shows an user's API usage broken down by day and endpoint, pointing out the endpoints that really consume API as well as those that do not (not_consuming_quota). The data available includes only the last 60 natural days and the required parameter is the user ID. (Check user ID) Additionally, you can specify the start day and last day parameters of the time range you want to track (yyyymmdd format).

4. Audit Log

4.1. Filtering logs

Web interface => From the My group menu option -> AUDIT LOG tab -> administrators can view the Audit Log, detailing the platform's most relevant actions. The log includes fields like Timestamp (UTC), Username, User Email, Source IP, Target Type, Target Identifier, and the Action taken.

Logs can be filtered using the collapsible left-side panel, which features key attributes like Date, User, Action and Target Identifier.

The User filter, along with the Username and User Email fields in the log table, all refer to the user who performed the action.

VirusTotal API => The /api/v3/groups/{group}/activity_log_entries endpoint retrieves a list of activity logs. It supports a filter query parameter that allows you to narrow the results using the same criteria available in the UI.

Be aware that unlike the UI (where Username and User Email are direct columns), the API requires you to access the user who performed the action through the dedicated user relationship. Consult the endpoint document for details.

4.2. Exporting logs

Web interface => From the My group menu option -> AUDIT LOG tab -> Export drop-down menu, administrators can export the Audit Log in CSV or Json format, or Copy to clipboard in JSON format. The current filters are applied to all exported logs.

VirusTotal API => Use the /api/v3/groups/{group}/activity_log_entries endpoint to retrieve activity logs in JSON format, applying the filters and relationships detailed in the endpoint documentation.

4.3. Seeing details

Web interface => From the My group menu option -> AUDIT LOG tab -> administrators can view the Audit Log of the platform's most relevant actions. For detailed context on an event, like which user was granted admin privileges or which user was removed from the group, admins can click the See details button located on the right of each log entry, which automatically displays the Audit Log Event Details.

VirusTotal API => The /api/v3/groups/{group}/activity_log_entries endpoint retrieves activity logs allowing the application of filters and relationships as detailed in the endpoint documentation.