Authentication overview

VirusTotal provides a public API that requires authentication to access its threat intelligence services. The primary method for authenticating API requests is through the use of API keys. These keys serve as unique identifiers that verify the identity of the requesting user or application, ensuring that only authorized entities can submit files, URLs, domains, or IP addresses for analysis and retrieve corresponding reports.

The API key model is a common authentication pattern for web services, offering a balance of simplicity and security for programmatic access. When an API key is included with a request, VirusTotal's servers validate it against their records. A valid key grants access to the requested resources, subject to the user's plan (e.g., community vs. premium) and associated rate limits. Invalid or missing keys typically result in an authentication error, denying access to the API functionality.

VirusTotal's API is designed for integrating threat intelligence into security operations, incident response workflows, and automated analysis systems. Proper management and secure handling of API keys are critical to maintaining the integrity and confidentiality of these integrations.

Supported authentication methods

VirusTotal exclusively utilizes API keys for authenticating requests to its public API. This method involves embedding a unique string, the API key, into each API request. The key acts as a secret token that grants access to the API services associated with the user's account.

The use of API keys simplifies the authentication process for developers, as it avoids the complexities often associated with token-based authentication flows like OAuth 2.0, which typically involve multiple steps for authorization and token exchange. While simpler, API keys require careful handling to prevent unauthorized access.

The following table outlines the authentication method supported by VirusTotal:

Method When to Use Security Level
API Key All programmatic access to VirusTotal's public API Medium (requires secure handling)

For detailed information on API key usage and specific request formats, refer to the VirusTotal API reference documentation.

Getting your credentials

To obtain your API key for VirusTotal, you must register for an account on the VirusTotal website. The process differs slightly for community (free) users and premium (paid) subscribers.

  1. For Community API Keys:
    1. Navigate to the VirusTotal registration page.
    2. Complete the registration form, providing a valid email address and creating a password.
    3. Verify your email address as instructed.
    4. Once logged in, go to your profile settings. Your API key will typically be displayed in a section labeled "API key" or similar. The community API key is intended for non-commercial use and comes with specific rate limits.
  2. For Premium API Keys:
    1. Premium API keys are provided to organizations that subscribe to VirusTotal's paid services. These services offer higher rate limits, advanced features, and dedicated support.
    2. To access premium services and obtain a premium API key, an organization must contact VirusTotal's sales team via the premium services page to arrange a custom enterprise pricing plan.
    3. After subscribing, the API key will typically be made available through the organization's VirusTotal enterprise console or provided directly by the VirusTotal team. Premium keys are designed for commercial applications and higher-volume integrations.

It is important to store your API key securely immediately after retrieval. Do not embed it directly into client-side code or publicly accessible repositories.

Authenticated request example

To make an authenticated request to the VirusTotal API, you typically include your API key in the request headers. The VirusTotal API expects the API key to be passed in the x-apikey header for most endpoints. Below is an example using curl to retrieve information about a specific file hash.

curl --request GET \
  --url https://www.virustotal.com/api/v3/files/275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f \
  --header 'x-apikey: YOUR_API_KEY' \
  --header 'accept: application/json'

In this example:

  • YOUR_API_KEY should be replaced with your actual VirusTotal API key.
  • The --url specifies the API endpoint for retrieving file information, using a SHA256 hash as an identifier.
  • The --header 'x-apikey: YOUR_API_KEY' line is where the authentication credential is provided.
  • The --header 'accept: application/json' indicates that the client prefers a JSON response.

For endpoints that involve submitting data (e.g., uploading a file for analysis), the API key is also included in the headers, and the request body contains the file or other relevant parameters. Always consult the specific endpoint documentation for exact request formats and required headers.

Security best practices

Securing your VirusTotal API key is crucial to prevent unauthorized access to your account and API usage, which could lead to exceeding rate limits or exposing sensitive information. Adhering to security best practices for API keys is essential for any integration.

  1. Treat API Keys as Sensitive Credentials: Your API key grants access to your VirusTotal account's API capabilities. Treat it with the same level of confidentiality as you would a password or private key.
  2. Avoid Hardcoding API Keys: Never embed API keys directly into your application's source code, especially if that code is publicly accessible (e.g., client-side JavaScript, public GitHub repositories). Hardcoding makes keys discoverable and vulnerable to theft.
  3. Use Environment Variables: For server-side applications, store API keys in environment variables. This keeps the key separate from the codebase and allows for easy rotation without modifying code. For example, in a Node.js application, you might access process.env.VIRUSTOTAL_API_KEY.
  4. Secure Configuration Files: If using configuration files, ensure they are not publicly accessible and are excluded from version control systems (e.g., via .gitignore). Encrypt configuration files where possible.
  5. Implement Server-Side Proxies: For client-side applications (e.g., web browsers, mobile apps), route API requests through a server-side proxy. The client calls your proxy, which then adds the API key and forwards the request to VirusTotal. This prevents the API key from ever being exposed in the client. This is a common pattern for securing access to third-party APIs from client-side code, as described in Google's API security best practices.
  6. Restrict Access to API Keys: Limit who has access to your API keys within your organization. Use access control mechanisms to ensure only authorized personnel can retrieve or manage them.
  7. Regularly Rotate API Keys: Periodically generate new API keys and revoke old ones. This minimizes the window of opportunity for a compromised key to be exploited. While VirusTotal's documentation does not explicitly detail key rotation mechanisms, it is a general security practice for API keys.
  8. Monitor API Usage: Keep an eye on your API usage statistics. Unusual spikes or activity patterns could indicate a compromised key.
  9. Secure Network Communication: Always use HTTPS when communicating with the VirusTotal API to encrypt data in transit, protecting your API key and request/response data from interception. The VirusTotal API endpoints are exclusively served over HTTPS.

By following these guidelines, you can significantly reduce the risk of your VirusTotal API key being compromised and ensure the secure operation of your integrations.