Use this guide when configuring an integration with your ServiceNow Configuration Management Database (CMDB). ServiceNow accepts HTTP basic authentication (use the **Basic Credentials** tab) or inbound REST API keys (**Washington DC** or later). A REST API key is bound to a ServiceNow user; roles and ACLs on that user govern Table API access the same way as with basic authentication. Synqly stores the REST API key value in the **Token** field in integration settings. Open the **Generating Credentials** tab you need. For creating the inbound profile, REST API key, and REST API Access Policy in ServiceNow, see [Inbound REST API Keys](https://www.servicenow.com/community/developer-advocate-blog/inbound-rest-api-keys/ba-p/2854924). Role assignments in each tab must still satisfy **Access scope and purpose**. ## Access scope and purpose The connection uses ServiceNow's **Table API** on the **Hardware** table (`cmdb_ci_hardware`). Decide what the application should be allowed to do, then grant matching roles (and optional ACLs) when you create the service account below. | Access | Purpose | | --- | --- | | Read hardware configuration items | List and look up existing hardware configuration items (CIs) so inventory views stay aligned with what is already in the CMDB. | | Create hardware configuration items | Add new hardware CIs when your process registers devices into ServiceNow. | Many environments start from the `cmdb_read` collection on the integration user, then add create rights only if you allow inserts. Your ServiceNow administrators may map these needs to different role names or stricter ACLs on your instance. ## Generating Credentials REST API keys are preferred when your instance supports them (**Washington DC** or later). The **Token** tab walks through the full ServiceNow sequence (plugin, inbound authentication profile, REST API Key record, REST API Access Policy)—then you paste the REST API key into Synqly's **Token** field. The **Basic Credentials** tab is shorter: create the same service user and role assignments, then set a password. The same CMDB collections apply in both tabs; only authentication differs. Basic credentials do not replace a REST API key if your team asked for one. Token (recommended) ### Roles for CMDB Hardware (REST API key path) Synqly authenticates Table API requests with a dedicated ServiceNow user tied to the REST API key. Collections on that user govern access to hardware CIs (`cmdb_ci_hardware`) as summarized under Access scope and purpose. Complete steps 1–3 first; assign collections on the integration user in step 4 using the tables immediately before that step. ### 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 plugin 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 Groups > Roles**. Click **New** and create a new custom role. Note the role name. **Role assignments** Collections on the integration user control reads (and related actions) against hardware CIs (`cmdb_ci_hardware`), consistent with Access scope and purpose. Apply these when you assign roles on the user in the next step: | Collection | Purpose | | --- | --- | | `cmdb_read` | Baseline read/list access on CMDB hardware aligned with how Synqly uses the Table API for inventory-style workflows. | | Custom role from step 3 | Include when administrators pair this user with the optional ACL in step 8 or otherwise require that role name on the user. | Choosing how much to assign—pick the scenario that matches your integration: Typical CMDB hardware read Assign on the user: `cmdb_read` and the custom role from step 3 when your process uses step 8 or admins require both. Inserts or extra ACLs Assign: Confirm with ServiceNow admins—this guide assumes the access needs described under Access scope and purpose. Authentication succeeds but hardware CIs look wrong—empty lists, missing fields, or unexpected denials—usually points to roles, ACLs, or stricter CMDB rules on the instance rather than the REST API key wiring. Re-check `cmdb_read`, the custom role from step 3 when step 8 applies, and Access scope and purpose. ### 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. In the **Roles** tab, select **Edit...**. Assign collections using the tables above—typically `cmdb_read` plus the custom role from step 3 when your administrators require that combination. ### 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 as a REST API key for an integration. In the **Auth Parameter** field, add **Auth Header** using the `x-sn-apikey` header field. This header carries the REST API key on each 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 4** as the **User**. Requests authenticated with this key use that user's roles and ACLs (for example `cmdb_read` and any custom role from step 3). Create the key by clicking **Save**. The system generates the REST API key value; use the lock icon to view it and copy the contents displayed below the field. Store it securely—you will paste it into Synqly's **Token** field. ### 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**. For typical integrations, leave **Apply to all methods** checked unless your security team requires a narrower policy (ServiceNow allows limiting methods or resources on the form). On the policy form, add the **Inbound Authentication Profile** from step 5 to the **embedded list** for authentication profiles, then click **Submit**. Without that link, ServiceNow may not apply your REST API key to Table API traffic even when the key and user look correct. ### 8. Create an ACL for table read/write access Some setups pair the custom role from step 3 with an explicit ACL on CI tables; read and other operations still depend on your CMDB roles and instance ACLs. Add this ACL only when required by your administrators. 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 **Hardware [cmdb_ci_hardware]**. In the **Roles** field under **Requires Role**, select the role created in step 3. Finalize the ACL by clicking **Submit**. If you use basic authentication for other integrations that use the Table API, add a **basic auth** authentication profile to this policy as well or create a separate policy for those integrations. ServiceNow applies authentication in priority order; adding only a REST API key authentication profile can change default basic auth behavior for Table API traffic covered by this policy. ### Configure the integration In your integration or connector settings, supply: **URL** The root URL of your ServiceNow instance, for example `https://.service-now.com/`. **Token** Paste the REST API key value from [Create an API Key](#assets-sn-token-step-6-create-api-key) into Synqly's **Token** field. Basic Credentials ### Roles for CMDB Hardware (basic credentials path) Synqly authenticates with HTTP basic credentials against the Hardware table (`cmdb_ci_hardware`). Collections on the integration user must match Access scope and purpose. Complete step 1, then assign roles in step 2 using the tables immediately before that step. ### Basic credentials — 1. Log in to ServiceNow as an Admin Once logged in, navigate to **All > Organization > Users**. **Role assignments** Collections to assign before you create the service account (step 2 below), consistent with Access scope and purpose: | Collection | Purpose | | --- | --- | | `cmdb_read` | Baseline read/list access on CMDB hardware aligned with Access scope and purpose. | | Custom role from administrators | Include only when administrators paired an optional ACL with that role or otherwise require it on the integration account. | Choosing how much to assign: Typical CMDB hardware read Assign on the user: `cmdb_read` and any custom role administrators require alongside it. Beyond this guide Assign: Confirm with ServiceNow admins if inserts or ACLs fall outside Access scope and purpose. Authentication succeeds but hardware CIs look wrong—re-check `cmdb_read`, any custom role your admins require, Access scope and purpose, and instance ACLs before changing credentials in Synqly. ### Basic credentials — 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. In the **Roles** tab, select **Edit...**. Assign collections using the tables above—typically `cmdb_read` plus any custom role administrators require. Finally, create a password for the user. Save the username and password in a secure location; you will need these values for the steps below. ### Basic credentials — Configure the integration In your integration or connector settings, supply: **URL** The root URL of your ServiceNow instance, for example `https://.service-now.com/`. **Username** The service account from [Basic credentials — 2. Create a Service Account User](#assets-sn-basic-step-2-service-account). **Password** Use with **Username** for HTTP basic authentication—the password for that service account.