> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup ServiceNow API Parameters

> Configure ServiceNow instance credentials in Genesis so agents can read and update ITSM records through the Table API.

## Overview

### Purpose

This guide covers **ServiceNow credential and connection setup** only. Save credentials in **Config -> Connections** — open **+ New Connection**, choose **ServiceNow** under **Dev Tools**, and complete the **Connection** tab. See [Connections — ServiceNow connections](/docs/Setup/Connections#servicenow-connections).

Once the connection is saved you have two ways to use it:

* To have Genesis **automatically pick up ServiceNow records** when they are assigned to the Genesis worker, enter a configured state, or mention Genesis in comments or work notes, continue to [ServiceNow Automation (Auto-Pickup)](/docs/Setup/ServiceNow-Automation).
* To use ServiceNow **manually from agents** (list, create, update records, add work notes, manage attachments), see [ServiceNow Connector Tools](/docs/Genbot-Toolkit/ServiceNow-Connector-Tools).

<Steps>
  <Step title="Verify ServiceNow access">
    Confirm you can reach the instance and that an integration user or OAuth client can call the Table API.
  </Step>

  <Step title="Choose an auth mode">
    Pick basic auth, OAuth client credentials, user OAuth, or a pre-issued bearer token based on how your instance is configured.
  </Step>

  <Step title="Save and test the connection">
    Run **Test Connection** in the Connections modal. Genesis probes `sys_user` with `sysparm_limit=1` and reports the connected identity when resolvable.
  </Step>

  <Step title="(Optional) Configure automation">
    Continue to [ServiceNow Automation (Auto-Pickup)](/docs/Setup/ServiceNow-Automation) when Eve should start work on matching tickets automatically.
  </Step>
</Steps>

## Connection fields

Every auth variant requires the **Instance URL** (`https://yourcompany.service-now.com`; https required). Genesis registers the host as a dynamic external-access endpoint.

| Mode label | Stored `auth_type` | Fields |
| - | - | - |
| **Integration User (Basic Auth)** | `basic` | `host` (required), `username` (required), `password` (required, secret) |
| **OAuth Client Credentials** | `client_credentials` | `host` (required), `client_id` (required), `client_secret` (required, secret), optional `token_url` (defaults to `<instance>/oauth_token.do`), optional `scopes` |
| **User OAuth (Authorization Code)** | `user_oauth` | `host` (required), plus per-connection OAuth client fields (see below) |
| **Pre-Issued Bearer / OIDC Token** | `bearer_token` | `host` (required), `bearer_token` (required, secret) |

### Integration user (basic auth)

Use a dedicated least-privilege ServiceNow user (for example `genesis.integration`) with roles that can read and update the tables Genesis monitors (`itil` is typical for incidents). Set the integration user's timezone to **GMT/UTC** so `sys_updated_on` comparisons in encoded queries behave predictably.

### OAuth client credentials

Requires the instance to allow the OAuth client-credentials grant (Utah+ with inbound client credential flows enabled). When `token_url` is left blank, Genesis defaults to `https://{host}/oauth_token.do`.

### User OAuth

Create an OAuth API endpoint for external clients in ServiceNow:

1. Go to **System OAuth -> Application Registry -> New -> Create an OAuth API endpoint for external clients**.
2. Register the redirect URI Genesis shows in the Connections modal.
3. Copy the generated **Client ID** and **Client Secret** into the connection.

Genesis pre-fills authorization and token URLs from your instance host:

* Authorization URL: `https://{host}/oauth_auth.do`
* Token URL: `https://{host}/oauth_token.do`
* Default scope: `useraccount`

The Connections UI suggests the OAuth connection name `servicenow_oauth_main`. User OAuth client fields can also inherit shared defaults from [OAuth Providers](/docs/Setup/OAuth-Providers) when left blank on the connection.

With User OAuth, each person signs in to ServiceNow in their browser, and Genesis acts in ServiceNow as that person:

* Anyone who can see the connection signs in from **Config -> Connections** (open the connection's OAuth setup guide and select **Connect**), or from the sign-in card an agent shows in chat the first time it needs ServiceNow.
* **Test** on the connection shows the ServiceNow user you signed in as.
* Genesis stores no ServiceNow passwords. Each person's tokens are stored as their own Genesis Secret and refreshed automatically; if a refresh fails, Genesis asks that person to sign in again.
* A ServiceNow change an agent makes for you is recorded in ServiceNow under your user. This holds when someone else approves the change in Action Review: the change is still made with your sign-in, not the approver's. The approver also needs their own ServiceNow sign-in on the connection to approve.
* If your sign-in has lapsed when someone approves your change, the change is not made and the request stays open, so it can be approved again after you sign in. If your access to the connection was removed, the change is not made.
* A User OAuth connection cannot be used for [ServiceNow Automation](/docs/Setup/ServiceNow-Automation), which runs with no person signed in. Use a separate integration-user or client-credentials connection for automation.

### Pre-issued bearer token

Use only when the instance is configured to accept externally issued bearer or OIDC access tokens. The `bearer_token` field is PAT-class for the `tools` category; roles need `access_pat_connections_tools` to create, update, or test this mode.

<Note>
  Unsupported or incomplete auth combinations fail explicitly — Genesis does not fall back to unauthenticated requests. Secrets are stored as Genesis Secrets and never logged.
</Note>

## Shared connections for automation

Scheduled ServiceNow automation and the **ServiceNow Ticket Poller** Flow run as a system principal, not as the connection owner. Use a **shared** integration-user or OAuth client-credentials connection for automation, and bind roles the scheduler user holds under **Roles with Access**. See [Scheduled flows that use Connections](/docs/User-Guide/Flows#scheduled-flows-that-use-connections).

## What it enables

After setup, Genesis can use `servicenow_connector_tools` to work with allowlisted ITSM tables (`incident`, `change_request`, `sc_request`, `sc_req_item`, plus any tables an admin adds through the `servicenow.extra_tables` setting). Deletes are never available through the connector.

## Related pages

* [ServiceNow Automation (Auto-Pickup)](/docs/Setup/ServiceNow-Automation)
* [ServiceNow Connector Tools](/docs/Genbot-Toolkit/ServiceNow-Connector-Tools)
* [Connections](/docs/Setup/Connections)
* [OAuth Providers](/docs/Setup/OAuth-Providers)