As previously highlighted, the VT Augment widget should be integrated via a bring-your-own-api-key model unless you have explicit written permission from VirusTotal to do it through a single integrator API key.
Integration dynamics
Your product should include some kind of settings view where your end-users may enter their own VirusTotal API key in order to power the integration, something similar to:
Your product will then interact with VirusTotal on behalf of your user, automatically enriching observables/alerts that are displayed in standard user journeys. Note the "enrichment" term, VT Augment should not be used for detection purposes, i.e. VirusTotal reports should not be used to generate alerts, but rather to add context to alerts that have been generated by your product with your own magic sauce.
Bring your own API key model
You should not use a single integrator API key in order to power the widget unless you have explicit written permission from VirusTotal. Instead, your end-users should each have an individual API key that they should insert in your product settings to activate the integration functionality.
End-users can register in VirusTotal in order to generate a free limited API key. This key is rate limited and functionally-constrained, but will allow them to power a basic version of the widget. In order to take full advantage of the integration users can license VT ENTERPRISE by contacting VirusTotal directly. It is a good idea to link to these resources in your integration activation flow, it will make the discovery process easier for users that may not be familiar with VirusTotal.
Generating the widget
The interaction with the VT Augment API is made up of two steps.
First, as an integrator you will call the /widget/url endpoint on behalf of your end-user, with their API key. This call will return a JSON object with the ephemeral widget report URL for the pertinent observable, and a detection ratio for it. The detection ratio allows you to embed a summary next to each observable listed in your interface and may serve as a trigger to display the full-fledged widget view.
In the second phase you will need to tie these ephemeral urls to your users' front-end events, so that when your user clicks on the widget trigger for a given observable (e.g. the detection ratio), they can see the HTML template with the report details.
What this effectively means is that the heavy lifting for rendering the widget can be performed either in the front-end (when the user views alerts) or the back-end (as alerts get produced and prior to the user viewing them, to speed up the process).
A front-end approach would have your back-end act as a pseudo-proxy communicating with VirusTotal, where the observable detection ratios and widget URLs would get requested as the user views alerts:
Now, to improve the user experience you might want to request the widget report URL prior to the user logging in to your platform, so that you can embed the iframe straight away in the templates that you serve to your users, without any AJAX involved. In this case the back-end would be doing much of the heavy lifting, in an asynchronous fashion, anticipating requests on behalf of the user. In this case the flow would look similar to this:
VT Augment client library
To help with the HTML response and ease the task of displaying the widget to your users, we have developed the VT Augment client library. The following code snippet surfaces the widget in a drawer.
var vtaugment = new VTAugment(container)
vtaugment.load("[ephemeral url]").openDrawer()
You can find the library and its documentation in this GitHub repository:
https://github.com/VirusTotal/vt-augment.