ServiceNow uses HTTP basic authentication with a username and password or token authentication to authenticate requests. This guide walks you through the setup process for both methods.

Authentication with a ServiceNow API Key

The preferred authentication method with ServiceNow is token authentication. You will need to create a token with the correct permissions. For more details, please see this guide from ServiceNow.

This authentication method is only available in the Washington DC ServiceNow release or later. Earlier versions will require you to use a username and password, which is detailed in the next section.

1. Log in to ServiceNow as an Admin

Once logged in, first verify that the API Key and HMAC Authentication plugin is enabled. Navigate to All > Admin Center > Application Manager and verify the plug API Key and HMAC Authentication (com.glide.tokenbased_auth) is activated. If it is not enabled, activate it.

2. Elevate Role

Once logged in, click on the face icon, and click on "Elevate Role". Click on "security_admin". This will allow you to create the necessary roles and permissions.

3. Create a Custom Role

Navigate to All -> System Security -> Users and Gropus -> Roles. Click New and create a new custom role. Note the role name

4. Create a Service Account User

This step is optional, but recommended rather than using an account of an employee. If the employee leaves and their account is deactivated, your API could stop working.

Navigate to All > Organization > Users. Select New from the upper right corner. Fill in the required fields, making sure to select the Internal Integration User field.

Once the user is created, select it from the list of all users. You will need to add a role to the user. In the Roles tab, select Edit... and add the following collections:

• sn_incident_write
• sn_incident_read
• itil_admin
• u_ticket_user

Also add the custom role created in step 3 to the user.

To enable access for the Security Incident Response Provider, assign the sn_si.manager role from the collections to grant access to the incident table.

To enable access for the WebHooks management functionality, assign the admin role from the collections to grant access to the 'sys_script' table.

5. Create the Inbound Authentication Profile

Navigate to All > System Web Services > API Access Policies > Inbound Authentication Profile. Click New and then click Create API Key authentication profiles.

Provide a name for the profile that reflects its use an API key for an integration.

In the Auth Parameter field, you must add Auth Header using the x-sn-apikey header field. This is the header that will be used to send the API key in the request.

Finally, click Submit.

6. Create an API Key

Navigate to All > System Web Services > API Access Policies > REST API Key. Click New and fill in a name for the key. Select the user created in Step 2 as the User. This will associate the key with the user, and the user's role assignment must have the following collections:

• sn_incident_write
• sn_incident_read
• itil_admin
• u_ticket_user

To enable access for the Security Incident Response Provider, assign the sn_si.manager role from the collections to grant access to the incident table.

To enable access for the WebHooks management functionality, assign the admin role from the collections to grant access to the 'sys_script' table.

Create the key by clicking Save.

The system generates a token; use the lock icon to view the token and copy the contents display below the field. Save this token in a secure location.

7. Set the API Access Policy

Navigate to All > System Web Services > API Access Policies > REST API Access Policies. Once there, click New.

Provide a descriptive name. Under REST API select "Table API". Verify that Apply to all methods is checked.

8. Create an ACL for table read/write access

Navigate to All > System Security > Access Control (ACL) > New.

In the Type field, select record. In the Operation field, select Create. In the Name field, select Incident .

In the Roles field under Requires Role, select the role created in step 3.

Finalize the ACL by clicking Submit.

Warning: 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 the basic auth integrations. This is necessary because 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.

Configure the Integration

Create your integration by supplying the following values.

URL The root URL of your ServiceNow instance. This may be in the format https://<tenant>.service-now.com/.

Token This is the API Key value gathered in step 4.

Authentication with a Service Now User Account

For ServiceNow instances that do not support API keys, you can use a user account to authenticate requests. This guide walks you through the process of creating a user account with the correct permissions.

1. Log in to ServiceNow as an Admin

Once logged in, navigate to All > Organization > Users.

2. Create a Service Account User

In the Users section, select New from the upper right corner. Fill in the required fields, making sure to select the Internal Integration User field.

This new user creation is optional, but recommended rather than using an account of an employee. If the employee leaves and their account is deactivated, your API could stop working.

Once the user is created, select it from the list of all users. You will need to add a role to the user. In the Roles tab, select "Edit..." and add the following collections:

• sn_incident_write
• sn_incident_read
• itil_admin
• u_ticket_user

For users engaged in Security Incident Response, assign the sn_si.manager role from the collections to grant access to the incident table.

For users engaged in WebHooks management, assign the admin role from the collections to grant access to the 'sys_script' table.

Finally, create a password for the user. Save the username and password in a secure location; you will need these values to configure the integration.

Configure the Integration

Create your integration by supplying the following values.

URL The root URL of your ServiceNow instance. This may be in the format https://<tenant>.service-now.com/.

Username The username of the user account created in step 2.

Password The password of the user account created in step 2.