# 1. Introduction

[Microsoft Defender for Endpoint](https://learn.microsoft.com/en-us/defender-endpoint/microsoft-defender-endpoint) is a comprehensive endpoint security platform that provides vulnerability management capabilities. This connector enables you to query vulnerability assets (device/machine inventory) and vulnerability findings (CVE-level vulnerability data) from Microsoft Defender for Endpoint.

# 2. Prerequisites

Before you begin, ensure you have:

* Access to an Azure account via the [Entra Portal](https://entra.microsoft.com/) or [Azure Portal](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)
* Permission to create new app registrations
* Microsoft Defender for Endpoint licensed and deployed in your environment
* Devices onboarded to Microsoft Defender for Endpoint


# 3. Create Application Registration

1. Log in to the Entra or Azure portal.
2. Navigate to "App registrations", then select "New registration".
3. Provide a name for your application (e.g., "Synqly Defender Vulnerabilities Connector").
4. Click "Register" to complete the application registration.
5. Be sure to note the **Application (client) ID** and **Directory (tenant) ID**.


# 4. Configure Permissions

1. Within the app registration you just created, navigate to "Manage" > "API Permissions".
2. Click "Add a permission".
3. Select "APIs my organization uses" and search for **"WindowsDefenderATP"** or **"Microsoft Defender for Endpoint"**.
4. Select **Application permissions** (not Delegated permissions).
5. Add the following permissions:
  * **Machine.Read.All** - Required to query device/machine inventory for vulnerability assets
  * **Vulnerability.Read.All** - Required to query vulnerability findings and CVE data
6. Click "Add permissions".
7. Click "Grant admin consent" for your tenant.
8. Before proceeding, verify the following:
  * All permissions you added are **Application permissions** and not Delegated permissions
  * All required permissions are present
  * Admin consent shows up as "granted" for your tenant


# 5. Create an API Key

1. Within the app registration you created earlier, navigate to "Manage" > "Certificates & secrets" > "Client secrets".
2. Click "New client secret".
3. Fill in a description and select an expiration period.
4. Click "Add" to create the secret.
5. Be sure to note the **Value** and **Secret ID**. Keep in mind you will not be able to view the secret value again after you navigate away from the page.


# 6. Determine URL

The Microsoft Defender for Endpoint API requires a base URL for your specific region. The base URL follows this format:
`https://api-{region}.securitycenter.microsoft.com`

For example:

- US region: `https://api-us.securitycenter.microsoft.com`
- EU region: `https://api-eu.securitycenter.microsoft.com`
- UK region: `https://api-uk.securitycenter.microsoft.com`


For most US-based tenants, you can also use `https://api.securitycenter.microsoft.com` which automatically routes to your region.

# 7. Configure the Integration

Create your integration by supplying all of the required values below:

**URL**: the regional API URL you determined in step 6 (e.g., `https://api-us.securitycenter.microsoft.com`).

**Client ID**: the Application (client) ID you gathered in step 3.

**Client Secret**: the client secret value you gathered in step 5.

**Tenant ID**: the Directory (tenant) ID you gathered in step 3.