# ServiceNow Application Vulnerability Response Configuration Guide

This guide walks you through configuring ServiceNow Application Vulnerability Response (AVR).

ServiceNow supports token (API key) authentication or basic authentication with a username and password. Select the appropriate tab below:

- **API key (recommended):** Token authentication with an inbound REST API key. Requires the Washington DC ServiceNow release or later.
- **Username and password:** Use a dedicated service account when your instance does not support API keys.


After authentication is set up, configure the integration using the values from your chosen path.

**Query only?** Complete credentials in the tab that matches your authentication method. If you use a REST API key (**API Key** tab), create the REST API Access Policies in that tab for the Table API.

**Using `create_findings`?** You must also complete the [ServiceNow Application Vulnerability Findings Import Setup Guide](/guides/provider-configuration/appsec-servicenow-findings-import-setup). That guide configures the Import Set staging table (`u_avr_staging`), transform map, and related AVR objects that Synqly posts findings to. When you use an API key, add an **Import Set API** REST API Access Policy (step 6 in the **API Key** tab). Basic credentials do not use REST API Access Policies—access is enforced through roles and ACLs.

## Access scope and purpose

The integration uses ServiceNow REST APIs against AVR tables. Query operations use the **Table API**. The `create_findings` operation posts JSON rows to the **Import Set REST API** (`/api/now/import/u_avr_staging/insertMultiple`). When you use a REST API key, each REST surface needs its own REST API Access Policy.

| Purpose | Access needed |
|  --- | --- |
| List discovered applications | AVR read (Table API) |
| List findings for an application | AVR read (Table API) |
| List application vulnerability findings | AVR read (Table API) |
| Get a single finding | AVR read (Table API) |
| Import findings into AVR (discovered applications, vulnerability entries, AVITs) | Import and AVR write roles; REST API Access Policy for Import Set API when using an API key; [import pipeline](/guides/provider-configuration/appsec-servicenow-findings-import-setup) |


## Instance prerequisites

Before starting, confirm:

| Requirement | Notes |
|  --- | --- |
| **Application Vulnerability Response (AVR)** | Installed and active; tables exist: `sn_vul_app_vulnerable_item`, `sn_vul_app_release`, `sn_vul_app_vul_entry` |
| **Integration user** | Dedicated user with Table API access for queries; additional import/transform and AVR write access for `create_findings` |
| **Normalized Severity Map** | Required for `create_findings` — source must match `u_source` values Synqly sends (default `Synqly AVR`) |


Suggested roles (adjust to your org):

- `import_transformer` or `import_admin` (for `create_findings`)
- AVR administrator or equivalent read/write roles on `sn_vul_app_*` tables
- CMDB read access for optional business application lookup during import


## Prerequisites

### Log in and create a service account

1. **Log in to ServiceNow** as an admin.
2. **Create a service account (recommended).** A dedicated account avoids broken integrations if an employee account is deactivated. Go to **All > Organization > Users**, select **New**, set **User ID** (required), select **Internal Integration User**, and complete any other required fields. Open the new user, go to the **Roles** tab, select **Edit...**, and assign roles that grant read access to Application Vulnerability Response records through the ServiceNow Table API.
For `create_findings`, also assign import/transform and AVR write roles as described under [Instance prerequisites](#instance-prerequisites).


Configuration

API Key (Recommended)
The preferred method is token authentication. For more details, see [this guide from ServiceNow](https://www.servicenow.com/community/developer-advocate-blog/inbound-rest-api-keys/ba-p/2854924).

API keys require the Washington DC ServiceNow release or later. Earlier instances need username and password; use the **Username and Password** tab.

### 1. Verify the API Key plugin

In **All > Admin Center > Application Manager**, search for **HMAC Authentication** and confirm **API Key and HMAC Authentication** (`com.glide.tokenbased_auth`) is activated. Activate it if it is not.

### 2. Elevate role

Open the user menu (face icon), choose **Elevate Role**, and select **security_admin** so you can configure API access.

### 3. Create the Inbound Authentication Profile

Go to **All > System Web Services > API Access Policies > Inbound Authentication Profile**. Click **New**, then **Create API Key authentication profiles**.

Give the profile a **name** that reflects an integration API key. In **Auth Parameter**, add **Auth Header** with the `x-sn-apikey` header. Click **Submit**.

### 4. Create an API Key

Go to **All > System Web Services > API Access Policies > REST API Key**. Click **New**, set a **name** for the key, and set **User** to the service account you created above. Click **Save**.

Use the lock icon to view and copy the token. Store it securely.

### 5. Set the Table API Access Policy

Go to **All > System Web Services > API Access Policies > REST API Access Policies** and click **New** (this may take a moment).

- **Name:** A descriptive name (for example, **Synqly Table API**).
- **REST API:** **Table API**.
- **Inbound authentication profiles:** Add the **Inbound Authentication Profile** you created in step 3, then **Submit**.


Confirm the new policy is **Active** with the scopes you expect. This policy is required for query operations (`query_applications`, `query_findings`, and related read APIs).

### 6. Import Set REST API access policy (create_findings only) {#appsec-sn-token-step-6-import-set-policy}

Required only when you use `create_findings`. Synqly posts finding rows to `/api/now/import/u_avr_staging/insertMultiple`.

Navigate to **All > System Web Services > API Access Policies > REST API Access Policies** and click **New**.

- **Name:** A descriptive name (for example, **Synqly Import Set**).
- **REST API:** **Import Set API** (the ServiceNow UI label for the Import Set REST API; paths resolve under `now/import/...`).
- **Inbound authentication profiles:** Add the **same** profile you added on the Table API policy in step 5, then **Submit**.


After you submit, confirm the new policy row is **Active**, then complete [ServiceNow Application Vulnerability Findings Import Setup Guide](/guides/provider-configuration/appsec-servicenow-findings-import-setup).

### Configure the integration (API key)

**URL**
The root URL of your ServiceNow instance, for example `https://<tenant>.service-now.com/`.

**Token**
The API key value from step 4.

Username and Password
For instances that do not support API keys, use basic authentication with the service account you created above.

Synqly authenticates with HTTP basic credentials against AVR tables. ServiceNow evaluates basic auth against the integration user's roles and ACLs directly—you do **not** create REST API Access Policies for this path.

Assign the integration user:

- Read access to AVR tables for query operations
- `import_transformer` or `import_admin` (or equivalent) for Import Set transform access
- AVR write roles on `sn_vul_app_release`, `sn_vul_app_vul_entry`, and `sn_vul_app_vulnerable_item` for `create_findings`
- CMDB read access if you rely on business application lookup during import


Then complete [ServiceNow Application Vulnerability Findings Import Setup Guide](/guides/provider-configuration/appsec-servicenow-findings-import-setup). Ensure the user can write to the staging table, transform maps, and AVR tables your administrators protect with ACLs.

### 1. Set a password

In **All > Organization > Users**, open the service account and set a password. Save the **User ID** and password securely; you will use them in Synqly.

### Configure the integration (basic auth)

**URL**
The root URL of your ServiceNow instance, for example `https://<tenant>.service-now.com/`.

**Username**
The **User ID** of the service account.

**Password**
The password for that user.

## Operation-specific setup

To enable `create_findings`, complete the [ServiceNow Application Vulnerability Findings Import Setup Guide](/guides/provider-configuration/appsec-servicenow-findings-import-setup) after you finish this guide. That guide configures the `u_avr_staging` Import Set table, REST Insert Multiple mapping, transform map, `onBefore` script, normalized severity map, and troubleshooting for AVR finding imports.

Credentials and roles from either tab work with `create_findings`. If you use the **API Key** tab, also create the Import Set REST API Access Policy in step 6 above. If you use **Username and Password**, ensure the integration user has the import/transform and AVR table roles/ACLs described above.