> For the complete documentation index, see [llms.txt](https://docs.rad.security/llms.txt).
> Use it to discover all available pages before exploring further.

# ServiceNow (ITSM)

Configure ServiceNow ITSM integration with RAD Security for automated security incident management.



<Callout kind="info">
**Beta Integration:** This integration is currently in beta. Features and setup steps may change as we refine the integration based on user feedback.
</Callout>

This guide walks you through integrating ServiceNow ITSM with RAD Security for automated security incident and ticket management, enabling you to automatically create, update, and track security incidents as ServiceNow issues.

ServiceNow provides powerful IT service management capabilities, making it ideal for managing security incidents, vulnerabilities, and remediation workflows in enterprise environments.

<Callout kind="info">
**Token Authentication Required:** This integration requires ServiceNow API Key (token-based) authentication, which is only available in the ServiceNow Washington DC release or later. Earlier versions are not supported.
</Callout>

## Prerequisites

Before you begin, ensure you have:

<Callout kind="success">
- Admin access to ServiceNow (Washington DC release or later)
- Ability to create users, roles, and API keys in ServiceNow
- The API Key and HMAC Authentication plugin enabled
- Access to RAD Security workspace with integration permissions
</Callout>

<Callout kind="info">
**Service User Recommended:** Create a dedicated service user for this integration rather than using a personal account. This ensures the integration continues working when team members leave or change roles.
</Callout>

---

## Step 1: Log in to ServiceNow as Admin

<Steps>
  <Step title="Access ServiceNow Admin">
    Log in to your ServiceNow instance with administrator privileges
  </Step>

  <Step title="Verify API Key Plugin">
    1. Navigate to **All > Admin Center > Application Manager**
    2. Verify the **API Key and HMAC Authentication** plugin (`com.glide.tokenbased_auth`) is activated
    3. If not enabled, activate the plugin before proceeding

    <Callout kind="alert">
    The API Key plugin is required for this integration and is only available in ServiceNow Washington DC release or later.
    </Callout>
  </Step>
</Steps>

---

## Step 2: Elevate Role and Create Custom Role

<Steps>
  <Step title="Elevate to Security Admin">
    1. Click on the **face icon** in the upper right corner
    2. Click **Elevate Role**
    3. Select **security_admin**

    <Callout kind="info">
    This elevation allows you to create the necessary roles and permissions for the integration.
    </Callout>
  </Step>

  <Step title="Create Custom Role">
    1. Navigate to **All > System Security > Users and Groups > Roles**
    2. Click **New**
    3. Create a new custom role with a descriptive name (e.g., "rad_security_integration")
    4. **Save and note the role name** for use in later steps

    <Callout kind="info">
    This custom role will be used to grant specific permissions to the service user for table access.
    </Callout>
  </Step>
</Steps>

---

## Step 3: Create Service Account User

<Steps>
  <Step title="Navigate to User Management">
    Navigate to **All > Organization > Users**
  </Step>

  <Step title="Create New User">
    1. Select **New** from the upper right corner
    2. Fill in the required fields, making sure to select the **Internal Integration User** field
  </Step>

  <Step title="Assign Roles to User">
    Once the user is created, select it from the list of users:

    1. In the **Roles** tab, select **Edit...**
    2. Add the following role collections:
       - `sn_incident_write` - Write access to incidents
       - `sn_incident_read` - Read access to incidents
       - `itil_admin` - ITIL administration
       - `u_ticket_user` - Ticket management
    3. Add the **custom role** you created in Step 2
    4. Click **Save**

  </Step>
</Steps>

<Callout kind="alert">
**Service User Strongly Recommended:** While you can use an existing user account, creating a dedicated service user is strongly recommended. If a personal account is used and that person leaves your organization, the integration will break.
</Callout>

---

## Step 4: Create Inbound Authentication Profile

<Steps>
  <Step title="Navigate to Authentication Profiles">
    Navigate to **All > System Web Services > API Access Policies > Inbound Authentication Profile**
  </Step>

  <Step title="Create API Key Profile">
    1. Click **New**
    2. Click **Create API Key authentication profiles**
    3. Provide a **name** for the profile
    4. In the **Auth Parameter** field, add **Auth Header** using the `x-sn-apikey` header field
    5. Click **Submit**

    <Callout kind="info">
    The `x-sn-apikey` header is the standard header used to send the API key in requests to ServiceNow.
    </Callout>

    <Callout kind="alert">
    **This profile is not attached to the API key.** The REST API Key record has no field for an authentication profile — do not go looking for one. You will link this profile to the Table API in [Step 6](#step-6-set-api-access-policy). Until you do, ServiceNow never evaluates the `x-sn-apikey` header and every request fails.
    </Callout>
  </Step>
</Steps>

---

## Step 5: Generate API Key

<Steps>
  <Step title="Navigate to REST API Keys">
    Navigate to **All > System Web Services > API Access Policies > REST API Key**
  </Step>

  <Step title="Create API Key">
    1. Click **New**
    2. Enter a **name** for the key (e.g., "RAD Security Integration Key")
    3. Select the **service user** created in Step 3 as the **User**
    4. Click **Save**

    <Callout kind="info">
    The API key will be associated with the service user and inherit all the user's role assignments.
    </Callout>
  </Step>

  <Step title="Copy API Key Token">
    1. After saving, the system generates a token
    2. Use the **lock icon** to view the token
    3. **Immediately copy the token** that appears below the field

    <Callout kind="alert">
    **Save this token securely!** You'll need it to configure the integration in RAD Security. Store it in a password manager or secrets vault.
    </Callout>
  </Step>
</Steps>

---

## Step 6: Set API Access Policy

<Steps>
  <Step title="Navigate to API Access Policies">
    Navigate to **All > System Web Services > API Access Policies > REST API Access Policies**
  </Step>

  <Step title="Create New Policy">
    1. Click **New**
    2. Provide a descriptive **name** (e.g., "RAD Security Table API Access")
    3. Under **REST API**, select **Table API**
    4. Verify that **Apply to all methods** is checked
  </Step>

  <Step title="Attach the Authentication Profile">
    1. In the **Authentication profile** embedded list near the bottom of the form, click **Insert a new row**
    2. Select the API Key authentication profile you created in [Step 4](#step-4-create-inbound-authentication-profile)
    3. Click **Submit** to save the policy

    <Callout kind="alert">
    **Do not skip this step.** This is the only place the authentication profile and the Table API are linked. If the profile is missing from this list, ServiceNow ignores the `x-sn-apikey` header entirely and every request returns `401 User Not Authenticated` — even though the API key itself looks correctly configured. This is the most common cause of a ServiceNow setup that appears complete but does not work.
    </Callout>
  </Step>
</Steps>

<Callout kind="info">
**How the three records fit together:** The **REST API Key** carries the *user*, which determines what data can be reached through ACLs. The **Inbound Authentication Profile** determines *how* an incoming request presents its key (the `x-sn-apikey` header). The **REST API Access Policy** is the only record where those two meet, by applying the authentication profile to the Table API. All three are required, and the key and the profile are never linked directly to each other.
</Callout>

---

## Step 7: Create ACL for Table Access

<Steps>
  <Step title="Navigate to Access Control">
    Navigate to **All > System Security > Access Control (ACL) > New**
  </Step>

  <Step title="Configure ACL">
    1. In the **Type** field, select **record**
    2. In the **Operation** field, select **Create**
    3. In the **Name** field, select **Incident**
    4. Under **Requires Role**, in the **Roles** field, select the **custom role** created in Step 2
    5. Click **Submit**

    <Callout kind="info">
    This ACL grants create permission on the Incident table to any user with the custom role you created.
    </Callout>
  </Step>
</Steps>

<Callout kind="alert">
**Important for Mixed Authentication:** If you are using basic authentication for other integrations that use the Table API, you will need to add a basic auth authentication profile to this policy as well, or create a separate policy for basic auth integrations. ServiceNow uses a priority system to determine which authentication method to use, and adding an API key authentication profile will override the default basic auth profile.
</Callout>

---

## Verify the ServiceNow Setup

Before configuring the integration in RAD Security, confirm the API key works directly against ServiceNow. RAD Security authenticates using exactly this header, so if these requests fail the integration will fail too.

<CodeGroup>

```bash
curl -i \
  -H "x-sn-apikey: YOUR_API_KEY" \
  -H "Accept: application/json" \
  "https://<instance>.service-now.com/api/now/table/incident?sysparm_limit=1"
```

```powershell
curl.exe -i `
  -H "x-sn-apikey: YOUR_API_KEY" `
  -H "Accept: application/json" `
  "https://<instance>.service-now.com/api/now/table/incident?sysparm_limit=1"
```

</CodeGroup>

<Callout kind="info">
On Windows, `curl` in PowerShell is an alias for `Invoke-WebRequest` and will not accept `-i` or `-H`. Call `curl.exe` explicitly, or run the command from `cmd.exe`.
</Callout>

Interpret the response:

| Response | Meaning |
|----------|---------|
| `200 OK` | Read access works — continue to the write check below |
| `401` with a `WWW-Authenticate: Basic` response header | The key was never evaluated. The authentication profile is not attached to the access policy ([Step 6](#step-6-set-api-access-policy)) |
| `401 User Not Authenticated` | The key is inactive, mistyped, expired, or the instance predates Washington DC |
| `403` / insufficient rights | Authentication works, but the service user lacks roles or ACLs ([Step 2](#step-2-elevate-role-and-create-custom-role), [Step 7](#step-7-create-acl-for-table-access)) |

A successful `GET` only proves read access. RAD Security creates incidents, so verify the write path as well:

```bash
curl -i -X POST \
  -H "x-sn-apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"short_description":"RAD Security connectivity test"}' \
  "https://<instance>.service-now.com/api/now/table/incident"
```

<Callout kind="alert">
Read-only access passing while creation fails is common — it means the ACL from [Step 7](#step-7-create-acl-for-table-access) is missing or does not use **Operation: Create**. Delete the test incident once the check succeeds.
</Callout>

---

## Step 8: Configure in RAD Security

Navigate to your RAD Security workspace and configure the ServiceNow ITSM integration with the following parameters:

### Required Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| **URL** | Root URL of your ServiceNow instance | `https://your-company.service-now.com/` |
| **Secret** | API Key token from Step 5 | `your-api-token-here` |

<Callout kind="info">
The URL should be your ServiceNow root URL in the format `https://<tenant>.service-now.com/` where `<tenant>` is your organization's ServiceNow instance name.
</Callout>

---

## Verify Integration

After completing the setup, verify your integration is working:

1. Navigate to **Data Sources > Integrations > Ticketing** in RAD Security
2. Locate your ServiceNow ITSM integration
3. Check the connection status shows as **Connected**
4. Test by creating a sample incident from RAD Security

<Callout kind="success">
Your ServiceNow ITSM integration is now configured! RAD Security can now automatically create and manage security incidents in ServiceNow.
</Callout>

## What Data is Synced

Once configured, RAD Security will sync the following with ServiceNow ITSM:

<ExpandableGroup>
  <Expandable title="Incident Creation" icon="ticket">
    - Automatically create ServiceNow incidents for security events
    - Include detailed incident context and metadata
    - Attach relevant threat intelligence
    - Add affected assets and resources
    - Include remediation recommendations
    - Populate standard ITIL fields
  </Expandable>

  <Expandable title="Custom Field Mapping" icon="sliders">
    - Map RAD Security fields to ServiceNow fields
    - Configure custom field values
    - Set default incident types
    - Define priority and urgency mappings
    - Configure assignment rules
    - Support for custom ServiceNow fields
  </Expandable>

  <Expandable title="ITSM Workflow Integration" icon="diagram-project">
    - Integrate with ServiceNow workflows
    - Trigger automated assignment rules
    - Leverage ServiceNow escalation policies
    - Support approval processes
    - Enable change management integration
  </Expandable>
</ExpandableGroup>

## Use Cases

<Columns cols={2}>
  <div>
  **Automated Incident Creation**
    Automatically create ServiceNow incidents when security events, vulnerabilities, or policy violations are detected.
  </div>

  <div>
  **ITSM Workflow Integration**
    Integrate security findings into existing IT service management workflows and processes.
  </div>

  <div>
  **Enterprise Incident Management**
    Manage security incidents alongside IT incidents in a centralized ITSM platform.
  </div>

  <div>
  **Compliance Tracking**
    Track security remediation efforts through ServiceNow's audit and compliance features.
  </div>
</Columns>

## Troubleshooting

<ExpandableGroup>
  <Expandable title="401 Unauthorized even though the API key looks correct" icon="lock">
    **Most likely cause:** The Inbound Authentication Profile created in [Step 4](#step-4-create-inbound-authentication-profile) was never added to the REST API Access Policy in [Step 6](#step-6-set-api-access-policy). Because the REST API Key record has no field for an authentication profile, a key that looks perfectly configured will still be rejected.

    **Solution:**
    1. Navigate to **All > System Web Services > API Access Policies > REST API Access Policies**
    2. Open the policy covering the **Table API**
    3. Confirm your API Key authentication profile appears in the **Authentication profile** embedded list, and add it if it is missing
    4. Confirm **Apply to all methods** is checked
    5. Re-run the verification request from [Verify the ServiceNow Setup](#verify-the-servicenow-setup)

    **Telltale sign:** If the `401` response carries a `WWW-Authenticate: Basic` header, ServiceNow never evaluated the API key and fell back to basic authentication. That confirms the profile is not linked to the policy.

    **Also check:** If **Auth Scope** is set on the REST API Key record, it must match the scope on the access policy. Leaving Auth Scope empty is valid and is the simplest working configuration.
  </Expandable>

  <Expandable title="Authentication Failed" icon="triangle-exclamation">
    **Possible causes:**
    - Authentication profile not attached to the REST API Access Policy (see the entry above)
    - API token is incorrect or expired
    - API token was revoked
    - Service user account was disabled or deleted
    - Incorrect ServiceNow instance URL

    **Solution:**
    - Verify the API token is copied correctly (no extra spaces)
    - Check that the service user account is still active
    - Try logging in to ServiceNow with the service user credentials
    - Generate a new API token if needed
    - Confirm the instance URL is correct
  </Expandable>

  <Expandable title="Insufficient Permissions" icon="shield-exclamation">
    **Possible causes:**
    - User missing required roles
    - Custom role not assigned
    - ACL not properly configured
    - User removed from necessary groups

    **Solution:**
    - Verify the service user has all required roles assigned
    - Check that the custom role is assigned to the user
    - Review ACL configuration for the Incident table
    - Ensure role collections are active and properly configured
    - Confirm no role restrictions have been added
  </Expandable>

  <Expandable title="Cannot Create Incidents" icon="ticket-slash">
    **Possible causes:**
    - Missing ACL permissions
    - Required fields not mapped
    - Table access restrictions
    - Workflow blocking creation

    **Solution:**
    - Verify the ACL for Incident table includes the custom role
    - Check that all required ServiceNow fields are properly mapped
    - Ensure the Incident table is accessible
    - Review ServiceNow workflow restrictions
    - Check ServiceNow business rules that might block creation
  </Expandable>

  <Expandable title="API Key Plugin Not Available" icon="plug-circle-xmark">
    **Possible causes:**
    - ServiceNow version is older than Washington DC release
    - Plugin not activated
    - License doesn't include API access

    **Solution:**
    - Verify your ServiceNow version supports API keys (Washington DC or later)
    - Check that the API Key and HMAC Authentication plugin is activated
    - Contact ServiceNow support about licensing if plugin is unavailable
    - Consider upgrading to a supported ServiceNow version
  </Expandable>

  <Expandable title="Wrong ServiceNow Instance URL" icon="globe">
    **Possible causes:**
    - Missing trailing slash
    - Incorrect instance name
    - Using developer instance URL format
    - Including additional path components

    **Solution:**
    - Ensure you're using the correct URL format: `https://<instance>.service-now.com/`
    - Include the trailing slash
    - Verify the instance name matches your organization
    - Don't include paths like `/api/` or `/incident.do`
  </Expandable>

  <Expandable title="Token Expired or Revoked" icon="key-skeleton">
    **Possible causes:**
    - Token was manually revoked
    - Service user was deleted or deactivated
    - Token reached configured expiration
    - API access policy changed

    **Solution:**
    - Log in as admin and verify the service user exists and is active
    - Navigate to REST API Keys and check if the token still exists
    - Check API access policies haven't changed
    - Create a new token if the old one was revoked
    - Update the token in RAD Security integration settings
  </Expandable>
</ExpandableGroup>

## Security Best Practices

<Columns cols={2}>
  <div>
  **Use Service Accounts**
    Always use a dedicated service account with a service email, never a personal account tied to an individual.
  </div>

  <div>
  **Least Privilege Access**
    Only grant the minimum permissions required. Use custom roles rather than admin privileges for integration accounts.
  </div>

  <div>
  **Rotate Tokens Regularly**
    Rotate API tokens every 90 days or according to your security policy to minimize risk of compromise.
  </div>

  <div>
  **Secure Token Storage**
    Store API tokens in a secure password manager or secrets vault. Never commit to version control or share via insecure channels.
  </div>

  <div>
  **Monitor Integration Activity**
    Regularly review incidents created by the integration to ensure proper operation and detect anomalies.
  </div>

  <div>
  **Audit Permissions**
    Periodically review the service user's role assignments and ACL configurations to ensure they remain appropriate.
  </div>

  <div>
  **Track Token Usage**
    Document which tokens are used for which integrations to simplify rotation and troubleshooting.
  </div>

  <div>
  **Enable MFA on Admin Accounts**
    Ensure admin accounts used to create service users and API keys have multi-factor authentication enabled.
  </div>
</Columns>

## Token Rotation

To rotate your ServiceNow API token:

<Steps>
  <Step title="Create New Token">
    1. Log in as admin to ServiceNow
    2. Navigate to **All > System Web Services > API Access Policies > REST API Key**
    3. Create a new API key for the same service user with a different name
    4. Copy the new token immediately
  </Step>

  <Step title="Update Integration">
    Update the token in RAD Security integration settings
  </Step>

  <Step title="Verify Connection">
    Test that the integration still works with the new token by creating a test incident
  </Step>

  <Step title="Revoke Old Token">
    Once verified, delete or deactivate the old token in ServiceNow
  </Step>
</Steps>

## Additional Resources

<Columns cols={2}>
  <Card title="ServiceNow API Key Authentication" icon="book" href="https://www.servicenow.com/community/developer-advocate-blog/inbound-rest-api-keys/ba-p/2854924" >
    Official ServiceNow guide to API key authentication
  </Card>

  <Card title="ServiceNow REST API Documentation" icon="code" href="https://docs.servicenow.com/bundle/vancouver-application-development/page/integrate/inbound-rest/concept/c_RESTAPI.html" >
    Learn about ServiceNow's REST API capabilities
  </Card>

  <Card title="ServiceNow Access Control" icon="shield" href="https://docs.servicenow.com/bundle/vancouver-platform-security/page/administer/security/concept/c_AccessControl.html" >
    Understand ServiceNow access control and ACL configuration
  </Card>

  <Card title="ServiceNow ITSM Best Practices" icon="list-check" href="https://www.servicenow.com/products/itsm.html" >
    ServiceNow IT Service Management overview and best practices
  </Card>
</Columns>

## Next Steps

<Columns cols={2}>
  <Card title="Ticketing Overview" icon="ticket" href="/rad-security/integrations/ticketing/overview" >
    Learn about other ticketing integrations
  </Card>

  <Card title="Jira Cloud" icon="jira" href="/rad-security/integrations/ticketing/jira-cloud-setup" >
    Add Jira Cloud for additional ticket management
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/rad-security/platform/workspace" >
    Configure custom workflows for incident response
  </Card>

  <Card title="Alerts & Incidents" icon="bell" href="/rad-security/platform/workspace" >
    Set up alert rules that trigger ServiceNow incident creation
  </Card>
</Columns>