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

# ServiceNow

> Let an agent work your ServiceNow records — find tickets, read comments, file and update records as each person, plus governed admin actions.

# ServiceNow

The ServiceNow integration lets an agent look things up and act in your
ServiceNow instance while it's talking to someone — find their incidents and
requests, read the latest comments and work notes, add a comment, file a catalog
request, search the knowledge base, and (when you enable it) update a record or
act on an approval.

It works in **two modes**:

* **On behalf of each person** — the agent acts as the signed-in user with their
  own ServiceNow account. It only ever sees and does what that person already
  can, because ServiceNow's own ACLs apply to every call.
* **On behalf of your organization** — a few privileged actions (the
  admin-fulfilment tools) run under an admin-authorized credential, governed by
  allowlists.

Setup takes a few minutes and is done once per instance.

## What it can do

The agent works across ServiceNow **record types** through one set of tools, so
"what tickets do I have open?" returns incidents, requests, and request items
together — each as a clickable deep link straight into ServiceNow.

| Record type                                                                                | Read                                   | Comment | Update                                              |
| ------------------------------------------------------------------------------------------ | -------------------------------------- | ------- | --------------------------------------------------- |
| Incidents                                                                                  | Yes                                    | Yes     | Off by default (enable to assign / change fields)   |
| Requests, Request items, Catalog tasks                                                     | Yes                                    | Yes     | Off by default                                      |
| Problems, Problem tasks, Tasks                                                             | Yes                                    | Yes     | Off by default                                      |
| Changes, Change tasks                                                                      | Yes                                    | Yes     | Read-only — governed by ServiceNow's change process |
| Ideas                                                                                      | Yes                                    | Yes     | Off by default                                      |
| Users                                                                                      | Yes                                    | —       | —                                                   |
| Knowledge articles                                                                         | Yes (search)                           | —       | —                                                   |
| Catalog items                                                                              | Yes (search)                           | —       | Submit a request (with confirmation)                |
| Approvals                                                                                  | Yes (your pending approvals)           | —       | Approve / reject — off by default                   |
| HR cases, Security incidents, Customer-service cases, CMDB, Groups, Locations, Departments | **Off** (sensitive — turn on per type) |         |                                                     |

Every record the agent mentions comes back with a deep link straight to it in
ServiceNow, rendered as a clickable markdown link.

## What it does **not** do (today)

* It does not edit a record type that's turned off, and it never edits a
  **Change** or **Approval** state through a raw field write — those follow
  ServiceNow's governed process (you enable approve/reject explicitly).
* It does not touch sensitive types (HR, SecOps, CMDB, org structure) unless you
  deliberately turn them on, one type at a time.
* It does not add OAuth scopes beyond reading what the signed-in user can already
  see. There is no broad service-account read of your instance.
* It never invents access: a person only ever sees what their own ServiceNow
  roles and ACLs allow. An **empty result means "nothing you can see," not
  "nothing exists"** — and the agent says so honestly rather than asserting there
  are none.

## Set up read & comment access (each person)

ServiceNow OAuth is **self-registered** — you create the OAuth application inside
your own ServiceNow instance and give Cobalt its client ID and secret. (Unlike
some integrations, Cobalt does not host a ServiceNow OAuth app for you.)

<Steps>
  <Step title="Add the integration">
    From your agent, open **Integrations**, choose **ServiceNow**, and enter your
    **subdomain** — the `acme` in `acme.service-now.com`.
  </Step>

  <Step title="Register an OAuth app in ServiceNow">
    In ServiceNow, go to **System OAuth → Application Registry** and create an
    **OAuth API endpoint for external clients**. Register **both** Cobalt redirect
    URLs — the admin callback and the end-user callback — on the **same** app. The
    redirect-URL field accepts a **comma-separated** list, so paste both. Copy the
    generated **Client ID** and **Client Secret**.
  </Step>

  <Step title="Enter the credentials in Cobalt">
    On the integration's **Authorization** tab, paste the subdomain, client ID,
    and client secret. Complete the admin **Connect with ServiceNow** flow — it
    should return **Verified**.
  </Step>

  <Step title="Attest to the access requested">
    Review the access the agent is asking for, confirm, name the integration, and
    save.
  </Step>

  <Step title="Let users authorize themselves">
    The first time the agent uses a ServiceNow tool for someone, that person is
    asked to authorize with ServiceNow in a popup. From then on the agent acts as
    them, and their own ACLs govern what they see — including which work notes are
    visible.
  </Step>
</Steps>

## Control what the agent may touch (Record types)

The **Record types** settings on the integration let you turn **read / comment /
update** on or off **per record type**. This replaces a coarse per-module switch
with one row per type, so you grant exactly what you intend.

* **Updates are off by default.** Reads and comments are low-risk; field updates
  are opt-in per type.
* **Sensitive types** (HR cases, security incidents, customer-service cases,
  CMDB, groups, locations, departments) are **off entirely by default**; turning
  one on asks you to confirm.
* **Changes and approvals are process-governed.** The agent reads and comments on
  changes, but never PATCHes their state directly. Approving or rejecting an
  approval is a separate, explicitly-enabled action (see below).

The agent works under four built-in safety gates, so an enabled update still
behaves predictably:

* **Read-before-write** — the agent never updates a record it hasn't just read
  this conversation. If it tries, it's told to read it first, and does.
* **Freshness** — if the record changed since the agent read it, the write is
  refused with "it changed since you read it"; the agent re-reads and retries.
* **Exact target** — a write whose selector matched zero or several records is
  refused until exactly one is identified.
* **Post-write verification** — after an update the agent re-reads the record and
  reports its **actual new state**, so you see what happened, not what was
  attempted.

## Approvals (optional)

The agent can always list a person's **own pending approvals** (it acts as them,
so it only sees approvals assigned to them). **Approving or rejecting** an
approval is a high-impact action and is **off by default** — enable **Approvals →
Update** in the Record-types settings to allow it. When enabled, an approve or
reject asks for confirmation, runs the same read-before-write and freshness
gates, and reports the approval's new state afterward. Every decision is audited.

## Troubleshooting

<Warning>
  **Subdomain format.** Enter only the subdomain (`acme`), not the full URL or
  `acme.service-now.com`. The field expects the instance name on its own.
</Warning>

* **The Authorize popup never opens / the card spins on "Authorizing…".** The
  OAuth client usually isn't registered correctly. Confirm the client ID and
  secret are entered on the **Authorization** tab and that the admin Connect flow
  shows **Verified** before an end user tries to authorize.
* **People are repeatedly asked to sign in to ServiceNow.** The OAuth app is
  usually missing one of the two redirect URLs. Both the admin and end-user
  callbacks must be registered on the **same** OAuth app, comma-separated.
* **"Invalid redirect URI."** The exact callback URL Cobalt shows must be
  registered on the ServiceNow OAuth app — copy it verbatim (both callbacks).
* **An update is refused as "read it first" or "it changed since you read it."**
  That's a safety gate working — the agent re-reads and retries on its own.
* **A privileged admin action says it needs authorization.** The organization
  credential for admin actions isn't set up yet, or its allowlist doesn't cover
  the target.
* **The agent says it can't find something you know exists.** It can only see what
  the asking person's ServiceNow account can. Check that person's roles and ACLs —
  work notes in particular are server-side filtered per user.

## FAQ

<AccordionGroup>
  <Accordion title="Does each person need their own ServiceNow login?">
    For reads, comments, creating requests, and updates — yes, the agent acts as
    them, so they authorize once. The admin-fulfilment actions run under the
    organization credential instead.
  </Accordion>

  <Accordion title="Will the agent expose records a person shouldn't see?">
    No. Reads and comments run with that person's own ServiceNow ACLs; the
    integration never widens them. Work notes are filtered by ServiceNow
    server-side, per user.
  </Accordion>

  <Accordion title="Can the agent change an incident's owner or state?">
    Only if you enable **Update** for that record type. Updates run the
    read-before-write, freshness, and exact-target gates and report the real new
    state afterward.
  </Accordion>

  <Accordion title="Why can't it edit a Change?">
    Changes follow ServiceNow's governed change process, so the agent reads and
    comments on them but never edits their state directly.
  </Accordion>

  <Accordion title="Do I need to add OAuth scopes for new record types?">
    No. The integration reads as the signed-in user (the `useraccount` scope), so
    turning on a record type doesn't require new ServiceNow scopes — only that the
    user's own ACLs permit it.
  </Accordion>

  <Accordion title="Is anything turned on automatically that I should know about?">
    Sensitive record types and all updates are off by default. You opt in per
    type, per action — read, comment, and update are independent switches.
  </Accordion>
</AccordionGroup>

## Related

* [Integrations overview](/integrations/overview) — how integrations work in
  general.
* [How Cobalt works](/concepts/how-cobalt-works) — where integrations fit.