Use this guide when configuring an integration with your ServiceNow Configuration Management Database (CMDB). ServiceNow accepts **OAuth 2.0 Client Credentials** (recommended) or **HTTP basic authentication**. Both methods authenticate as a dedicated service account; that user's roles and ACLs govern all API access. Open the **Generating Credentials** section and choose the tab for your authentication method. 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`). Some flows also call the **Identification and Reconciliation API** (`/api/now/identifyreconcile`). Decide what the integration should be allowed to do, then grant matching roles (and optional ACLs) when you create the service account or link the Application User 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 ServiceNow supports two authentication methods for this integration, shown as tabs below. **OAuth 2.0 (recommended)** — A Client Credentials application that authenticates as a linked Application User. Access is governed entirely by that user's roles, with no REST API Access Policies required. **Basic Credentials** — A dedicated service account with username and password. Setup is shorter: create the user, assign the CMDB roles listed in that tab, and set a password. The same CMDB collections apply in both tabs; only authentication differs. OAuth 2.0 (recommended) ### Roles for CMDB Hardware (OAuth path) OAuth 2.0 requests are authenticated as the **Application User** linked to the OAuth Application Registry. Collections on that user govern access to hardware CIs (`cmdb_ci_hardware`) exactly as they do for Basic Credentials. Complete the portal steps below, then assign roles on the Application User in step 4. ServiceNow authenticates this method with an OAuth 2.0 **Client Credentials** application. With this approach, you authenticate an *application* (using a Client ID and Client Secret) that then acts as a linked **OAuth application user**. The application credentials themselves carry no permissions—that user's roles and ACLs determine what the integration can read or write, exactly as they would for Basic Credentials, but without embedding a username or password in the integration settings. ### 1. Verify the Client Credentials grant type is enabled In the ServiceNow filter navigator, type `sys_properties.list` and press **Enter**. Search for `glide.oauth.inbound.client.credential.grant_type.enabled` and confirm its value is **true**. On instances running the Zurich release or later (where the Machine Identity Console is available), this property is typically already set to **true**. If you can see the Machine Identity Console in the navigation, you can skip this step and return here only if token requests fail with `access_denied`. If the property does not exist, click **New** and create it: set **Name** to `glide.oauth.inbound.client.credential.grant_type.enabled`, **Type** to `true | false`, and **Value** to `true`. ### 2. Create the OAuth integration Navigate to **All > Machine Identity Console**, then click the **Inbound integrations** tab. Click **New Integration**. In the **"Select your application connection type"** dialog, select **OAuth - Client credentials grant** ("Used for machine-to-machine access to the application without the user's context"). Fill in the **Details** section: | Field | Value | | --- | --- | | Name | A descriptive name, for example `Synqly Integration`. | | Provider name | A label for the external system connecting to ServiceNow, for example `Synqly`. | | OAuth application user | The service account that should own tokens issued from this integration. This is the key field—the token acts as this user, and that user's roles and ACLs govern all API access. | | Client ID | Auto-generated. | | Client secret | Auto-generated. | In the **Auth scope** section, leave **Auth scope** empty and **uncheck** the **Allow access only to APIs in selected scope** checkbox. **Unchecking "Allow access only to APIs in selected scope" is required.** When unchecked, access is governed entirely by the **OAuth application user**'s roles and ACLs. If the checkbox is left checked or an Auth scope is added, different ServiceNow REST surfaces require different scopes and will conflict with each other, producing `403: Missing required api access scope` or `403: Access to unscoped api is not allowed` errors. Click **Save**. The Client secret is masked after saving. Copy it before clicking Save, or use the copy icon next to the field on the saved record. Store both the Client ID and Client secret securely; you will need them when configuring the integration in Synqly. ### 3. Confirm the Application User The **OAuth application user** is set directly on the creation form in step 2. Verify that the correct service account is selected before saving. Do not create a REST API Access Policy that enforces a specific Auth Scope (for example on `table_api_access`) for OAuth traffic. Combining this integration with REST API Access Policies produces `403` scope-conflict errors identical to those described in step 2 above. ### Dependency chain ``` Client ID + Client Secret | (authenticate) v OAuth Integration Record | (acts as) v OAuth Application User | (governed by) v Roles and ACLs | v What the token can read or write ``` The OAuth credentials themselves grant no permissions on their own—they are a key to the door. What is behind that door is defined entirely by the OAuth application user's roles, assigned in the next step below. ### 4. Assign roles to the Application User Open the Application User you set in step 2 and, in the **Roles** tab, select **Edit...**. Assign: | 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. | ### Configure the integration In your integration or connector settings, supply: **URL** The root URL of your ServiceNow instance, for example `https://.service-now.com/`. **Client ID** The Client ID from the Application Registry record. **Client Secret** The Client Secret from the Application Registry record. **Token URL** (optional) Only set this if your identity provider issues tokens from a URL other than your ServiceNow instance's default OAuth token endpoint. **OAuth Scopes** (optional) Leave empty for a Broadly scoped Application Registry (recommended). Only set this if the registry is Securely scoped with explicit Auth Scopes—see the warning in step 2 above. 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. Assign roles in step 1, then create the service account in step 2. **Role assignments** | 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. | If 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. ### 1. Create a Service Account User 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. This step is optional but recommended rather than using an employee account. 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. Create a password for the user. Save the username and password in a secure location; you will need these values for the steps below. ### 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 [1. Create a Service Account User](#assets-sn-basic-service-account). **Password** Use with **Username** for HTTP basic authentication—the password for that service account.