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](https://www.servicenow.com/community/developer-advocate-blog/inbound-rest-api-keys/ba-p/2854924). 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://.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://.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.