Set up the Bitdefender integration

Bitdefender GravityZone is a cloud-managed endpoint security platform. When you connect it to octoja, the Bitdefender Protection check shows for every device whether the local Bitdefender agent is running, whether its signatures are current and whether real-time protection is active — plus the quarantined threats and EDR incidents that GravityZone reports for that device. While the integration is in beta, its card on the Integrations page carries a BETA badge.

Prerequisites

• You need the Integration Management permission in octoja. Administrators assign permissions to groups under Administration → Groups.
• You need a GravityZone Control Center API key from the partner account that manages your customers' companies — a key only sees the companies below its own account.
• Know which cloud region your GravityZone tenant lives in: the EU cloud (cloudgz.gravityzone.bitdefender.com) or the non-EU cloud (cloud.gravityzone.bitdefender.com). An API key only works against its own region.
• The Bitdefender Protection check runs on Windows and macOS devices with Bitdefender Endpoint Security installed.

Create an API key in GravityZone

1. Sign in to GravityZone Control Center using an administrator account in your partner company.
2. Open the user menu in the upper-right corner and select My Account.
3. In the API keys section, click Add and enter a description, for example octoja.
4. Enable Companies, Network, Quarantine and Incidents. For automated Bitdefender agent rollout, also enable Packages.
5. Click Generate and copy the generated key before closing the window. GravityZone only shows it once. Store it securely, then paste it into octoja as described in the next section.

The Bitdefender API key instructions show the GravityZone screens and list the required account rights.

Connect Bitdefender

1. Go to Administration → Integrations. Under Other platforms, find the Bitdefender card — it carries the BETA and Antivirus badges — and click Set up.
2. In the Set up Bitdefender dialog, paste your API key and pick your Cloud region.
3. Optionally click Test connection. A green "API key verified." line confirms a working key; a red "Bitdefender rejected this API key." line shows Bitdefender's reason if it is rejected.
4. Click Save. octoja checks the key against GravityZone before storing it, so a rejected key is never saved — the dialog stays open and reports "The provided Bitdefender GravityZone API key was rejected." On success the card switches to its connected layout: a Customers matched progress bar plus the Match customers button and the Disconnect icon. octoja stores the key in your instance configuration and never returns it through the API.

Match customers to GravityZone companies

octoja customers and GravityZone companies are independent records — after connecting you tell octoja which is which. The pairing is one-to-one in both directions: each octoja customer maps to at most one GravityZone company, and each GravityZone company to at most one octoja customer. Pick the same company on two rows and saving fails with "A Bitdefender company can be matched to at most one customer."

1. On the Bitdefender card, click Match customers.
2. The dialog lists each octoja customer in a row. Pick the matching GravityZone company from the picker on each row — the picker shows each company's Company ID so you can tell same-named companies apart. Leave a row empty if the customer is not in GravityZone.
3. Click Save. The progress bar on the card is red until the first customer is matched, amber while the mapping is partial, and green once every octoja customer is matched.

If companies are missing from the picker: the list contains exactly the companies that are managed under the account your API key was created in. Companies managed in a different partner account never appear — create the key in the account that manages them. If the dialog reports "Could not load companies", the key may no longer be valid or the account it belongs to is not a partner account.

Your matches are preserved across disconnect and reconnect — you do not lose the mapping when rotating the API key.

When you save, every matched customer automatically gets the customer tag bitdefender. Use it, for example, to target these customers through Customer Tags in a config package's targeting rules, see Assign checks with config packages. Removing a match does not remove the tag from the customer; remove it on the customer itself if needed.

Matching links customers, not devices. Devices link automatically: the Bitdefender Protection check reads the GravityZone endpoint ID from the local agent, and octoja attaches the cloud data to the device through that ID. A device only shows GravityZone threat data when its own octoja customer is matched to the GravityZone company the device belongs to — if quarantine and incident data stays empty on a device whose health rows work, check that mapping first.

Add the check to your devices

The integration brings the Bitdefender Protection check. Assign it like any other check: open a device, switch to its Checks tab and click Add Check — or roll it out to many devices at once with a config package. The check runs on the device itself and reads the locally installed Bitdefender Endpoint Security, so the Bitdefender agent must be installed on the device; the health rows work even without the cloud connection. By default the check runs every 5 minutes.

Install the Bitdefender agent automatically

The Roll out Bitdefender agent automation action installs a missing Bitdefender agent on Windows devices. The step fails on Linux and macOS, so restrict the automation to Windows devices. You need a connected integration, the device's customer matched to a GravityZone company, and an existing Windows installation package in that company.

1. Create an automation targeting the Windows devices and add a Roll out Bitdefender agent step.
2. Leave Installation package empty if each matched company has exactly one endpoint agent package. octoja then selects that customer's package. If there are several packages, enter the name of the one to use.
3. Save the automation and check a run on a test device first. In the step's outputs, action is either installed or alreadyInstalled; installed indicates whether the agent is present. An existing agent is not reinstalled.

If the customer match is missing or octoja cannot select an unambiguous installation package, the step fails with an explanatory message. Check the mapping and package name. A successful rollout does not replace protection monitoring: also assign Bitdefender Protection to monitor services, signatures and real-time protection.

Values and thresholds

What the check shows on the device and how to set the thresholds for signature age, real-time protection and quarantine is described in Bitdefender Protection.

What the integration card shows

Once connected, the Bitdefender card on the Integrations page aggregates across all matched companies: Endpoints with threats and EDR incidents as counts, and a warning line "Companies without EDR license" when some matched companies have no EDR add-on. The two counts appear only once at least one of them is above zero — on a clean estate the card shows the progress bar alone.

Rotate the key or disconnect

• Bitdefender has rejected your key: the card shows "The API key is no longer valid. Update it to keep receiving data from Bitdefender." and an Update credentials button. Click it and save the new key.
• Disconnect: click the Disconnect icon and confirm. The API key is removed; your customer matches are preserved in case you reconnect later.

Tips

• If a device reports "Bitdefender Endpoint Security was not detected on this device.", the Bitdefender agent is not installed there — the check reports a warning, not a failure.
• If the health rows work but the Quarantine list and EDR incidents stay empty, verify under Match customers that the device's customer is matched to the GravityZone company the device actually belongs to.
• GravityZone threat data is refreshed about every 5 minutes — new detections appear on the device shortly after they show up in the GravityZone console.

Related articles

• Assign checks with config packages
• Set up lywand software
• ESET Security
• Securepoint Antivirus Pro

FAQ

Why does the Endpoint ID differ from the ID in the GravityZone address?

The check reads Endpoint ID from the local Bitdefender agent. Bitdefender distinguishes it from computer_id, so the two can differ for the same device. Find the device in GravityZone by customer and device name rather than converting one ID into the other. The difference alone does not indicate an incorrect match.