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

# ServiceNow

> Verify callers from Incident, Interaction, and Requested Item records with the TruU Identity Verification app. Install, assign roles, connect with a one-time link, and see results as work notes on the record.

## About ServiceNow

The TruU Identity Verification app lets help desk agents verify a caller from the record they are already working, before a password reset, MFA reset, or account recovery. The agent chooses **Verify Identity**, TruU sends the caller a verification link, and progress and the final result come back to the record as work notes.

This connector **starts** verifications, both for agents working a record and for employees through your own catalog items (see [Self-service with Flow Designer](#self-service-with-flow-designer)). The app is a scoped application (`x_truu_idv`). It adds:

![ServiceNow Interaction record with the Verify identity dialog open, showing Send to, Delivery method set to email, and a Reason field, with TruU work notes on the right](https://mintcdn.com/truu-2/ggexkQvmOZdl3yHs/images/idv/servicenow-verify-identity.png?fit=max\&auto=format\&n=ggexkQvmOZdl3yHs\&q=85\&s=f2937fe89c25d164eec09d2ed52a06ef)

An agent chooses Verify Identity on an Interaction. The link goes to the contact on file, and progress comes back as work notes.

* A **Verify Identity** action on Incident, Interaction, and Requested Item records.
* A **Verification Requests** list.
* A **TruU: Verify Identity and Wait** subflow and a **TruU: Create Verification Request** action for Flow Designer.
* **Privacy Policy** and **Contact Support** links in the app menu.
* Three roles for people, plus an integration role that Connect assigns to the app's own integration user.

## Prerequisites

* **ServiceNow:** ITSM with Incident, Interaction Management, or Service Catalog, depending on the records you want the action on.
* **TruU:** an **Owner** or **Admin** seat, a connected directory (Entra ID or Okta), and email or SMS delivery for the people agents will verify.
* **Network:** see [Network](#network). No MID Server is needed.

## Install and assign roles

**1. Get the app**

Email [idv@truu.ai](mailto:idv@truu.ai) for the TruU Identity Verification update set (XML), then load, preview and commit it in your instance under **System Update Sets → Retrieved Update Sets**.

**2. Assign roles**

| Role | Who needs it | Grants |
| - | - | - |
| `x_truu_idv.admin` | The admin who connects the app and manages its settings | Connect to TruU page, app settings |
| `x_truu_idv.agent` | Agents who run verifications | The Verify Identity action on records |
| `x_truu_idv.verification_request_user` | Anyone who needs to see verification history | The Verification Requests list |

The app also ships `x_truu_idv.integration`. Connect assigns it to the app's integration user (see [How TruU authenticates to your instance](#how-truu-authenticates-to-your-instance)). Don't assign it to people.

## Connect to TruU

![ServiceNow connector page with the ServiceNow tenant field, Generate connect link, and the Prefer manual setup steps](https://mintcdn.com/truu-2/ggexkQvmOZdl3yHs/images/idv/settings-servicenow-light.png?fit=max\&auto=format\&n=ggexkQvmOZdl3yHs\&q=85\&s=8c02fcab0de7451e71d5f688666b0bcd)

You do not copy credentials by hand. A one-time connect link sets up the connection in both directions.

**1. Generate a connect link**

In the IDV Console, go to **Settings → Connectors → ServiceNow**, enter your **ServiceNow tenant** (the subdomain of your instance URL, for example `dev123123`), and choose **Generate connect link**. The link works once and expires after 15 minutes.

**2. Open it in your instance**

Open the link while signed in to your instance with the `x_truu_idv.admin` role. It opens the app's **Connect to TruU** page with the linking code filled in.

**3. Connect**

Accept the TruU Terms of Service and Privacy Statement, then select **Connect**. The page does not connect until you do. Connect:

1. Creates a web-service-only user, `truu.idv.integration`, with the `x_truu_idv.integration` role.
2. Creates an OAuth client named **TruU Identity Verification** that runs as that user, with a new random secret. On a reconnect, it replaces the previous client only once TruU has accepted the new one.
3. Checks that your instance issues a client-credentials token to that client, before the linking code is used.
4. Sends TruU the OAuth client ID and secret, and stores the TruU API key in an encrypted property that only `x_truu_idv.admin` can read or change.

Nothing is shown to you or copied by hand. The Verify Identity action appears once the connection is complete.

> [!WARNING]
>
> **One time per instance: turn on OAuth client credentials.** ServiceNow turns the client-credentials grant off by default. If it is off, Connect stops before it uses the linking code and shows **Open the property to turn it on**. That opens a new system property, `glide.oauth.inbound.client.credential.grant_type.enabled`, already set to `true`. Save it, return to the Connect page and select **Connect** again. The setting only affects OAuth clients configured for client credentials. See ServiceNow's [Client Credentials](https://www.servicenow.com/docs/r/oL66E_cwDD_tnWQYzYPRdA/mBHRF97W4Ou6s_~Ts5ooFA) documentation.

> [!NOTE]
>
> Connect from the **Global** application. The OAuth client is a Global record, and ServiceNow won't save it while the application picker is set to a scoped app. Connect tells you if this happens.

> [!NOTE]
>
> If you aren't the ServiceNow admin, send them the connect link. They open it while signed in with the `x_truu_idv.admin` role and select **Connect**. The link still works once and expires after 15 minutes.

To replace the app's credentials at any time, generate a new connect link and connect again. Connecting again reuses the integration user and creates a new OAuth client. Only after TruU accepts the new client does the app delete the previous one, which revokes what TruU held before. If the attempt fails (for example, the code expired), the existing connection keeps working.

The connection stays tied to the instance it was made from: TruU won't send its OAuth credentials anywhere else, and the events endpoint can't be moved to another instance in the console. To move to a different instance, connect from that instance with a new connect link.

> [accordion] Can't open the link?
>
> Under the connect link, the console also shows the bare linking code. Copy it, open the app's **Connect to TruU** page in your instance (**TruU Identity Verification → Connect to TruU**), paste the code and select **Connect**. The same 15-minute, single-use rules apply.
>
> There is no manual setup that skips the Connect page: the integration user and OAuth client that TruU authenticates with are created there.

## How TruU authenticates to your instance

The app's events endpoint, `/api/x_truu_idv/truu_idv/events`, is not public. ServiceNow accepts a call to it only when it is authenticated and the caller holds `x_truu_idv.integration`.

* **TruU to your instance:** TruU requests an access token from your instance's `/oauth_token.do` with the OAuth client created at Connect (client-credentials grant) and sends it as a bearer token with each event. The token runs as `truu.idv.integration`, which can't sign in to the UI and has no password. TruU reuses a token until shortly before it expires and requests a new one when your instance rejects it.
* **Your instance to TruU:** the app calls the TruU API with its API key, stored as an encrypted property that only `x_truu_idv.admin` can read or change.
* **Rate limit:** the endpoint allows 3,600 requests per hour for the integration role. Find it under **System Web Services → REST → Rate Limit Rules** as **TruU IDV events**.

To cut TruU off from your instance, deactivate the **TruU Identity Verification** OAuth client (**System OAuth → Application Registry**) or the `truu.idv.integration` user. Connecting again turns both back on.

## What the app reads and writes

| Action | Data | Direction |
| - | - | - |
| Create a verification from a record | The caller from the record (email and phone), the record reference, the delivery method the agent chose | ServiceNow → TruU |
| Send the caller a link | Delivered by TruU to the caller's directory contact by email or SMS, or copied by the agent | TruU → caller |
| Report progress and the result | Work notes on the record (link sent, in progress, verified, failed, cancelled). On Incident and Interaction, a TruU Status field and a TruU Verifications related list | TruU → ServiceNow |

TruU does not read ServiceNow tables. The only calls TruU makes into your instance are requesting an OAuth token and delivering verification events to the app.

## Network

| Direction | From | To | Port |
| - | - | - | - |
| Outbound | Your instance | `agent.truu.ai` | 443 |
| Inbound | TruU | Your instance's public endpoint (`*.service-now.com`): `/oauth_token.do` and the app's events endpoint only, authenticated with OAuth 2.0 client credentials | 443 |

No MID Server, VPN, or inbound firewall change on your own network is needed.

## Settings admins change

The app's settings are under its **Properties** module and require `x_truu_idv.admin`.

| Setting | Default | What it does |
| - | - | - |
| Enabled | On | Turns the Verify Identity action on or off for all agents |
| Allow SMS | On | Whether agents can choose SMS delivery. Turn off if your organization restricts SMS |
| Show on Incident, Interaction, Requested Item | On for each | Which record types show the action |
| Link expiry (minutes) | 30 | A placeholder shown until TruU replies. The real expiry comes from the use case and is written back to the record. |

Leave the API base URL property blank. Blank means the app uses the TruU API at `agent.truu.ai`; change it only if TruU support asks you to.

## Flow Designer

Use the app's Flow Designer content to require verification inside your own catalog items or automations.

| Content | Type | Use it to |
| - | - | - |
| TruU: Verify Identity and Wait | Subflow | Send a verification and pause the flow until the person has verified, failed, or the link expired |
| TruU: Create Verification Request | Action | Send a verification and continue without waiting |

> [!WARNING]
>
> Publish the **TruU: Verify Identity and Wait** subflow after you install or upgrade the app. It installs as a draft, and flows that call it fail until it is published.

### Self-service with Flow Designer

Employees can verify themselves from the ServiceNow portal, with no agent involved: put verification in front of a catalog item such as "Reset my MFA".

**1. Create a flow on the catalog item**

In Flow Designer, create a flow with the **Service Catalog** trigger for your catalog item.

**2. Add the subflow**

Add **TruU: Verify Identity and Wait** as the first action and set its inputs:

| Input | Set it to |
| - | - |
| **Subject User** | The requested-for user from the trigger's requested item |
| **Use Case** | **Help desk**, **Pre-hire** or **Password reset**. These send the Helpdesk, Onboarding and Credential reset use cases. |
| **Delivery** | **Email** (default) or **SMS**. Use SMS for resets: someone locked out often can't reach their mailbox. |
| **Reason** | Shown on the request, for example "Self-service MFA reset" |
| **Source Table** and **Source Record** | `sc_req_item` and the requested item's sys\_id, so results are written back to it |

**3. Act on the result**

The subflow returns **Verified** (true or false) and the **Verification Request** record. Add a flow condition so the fulfillment steps run only when **Verified** is true.

![ServiceNow Flow Designer with a Service Catalog trigger and the TruU: Verify Identity and Wait subflow, showing Subject User, Use Case, Reason, Source Table and Source Record inputs](https://mintcdn.com/truu-2/ggexkQvmOZdl3yHs/images/idv/servicenow-flow-designer.png?fit=max\&auto=format\&n=ggexkQvmOZdl3yHs\&q=85\&s=21090ffc169135e5073af3021b7024eb)

A Service Catalog flow that verifies the requester before fulfillment.

The use case you pick decides the flow and what happens after, so a **Password reset** catalog item can also issue a Windows Temporary Access Pass or reset PingOne MFA automatically. See [How use cases work](https://docs.truu.ai/idv/use-cases/overview.md).

## Verifying the connection

1. In the IDV Console, run **Test connection** on the ServiceNow connector. It sends a test event to your instance and reports the result.
2. Open a test Incident, choose **Verify Identity**, and send a link to a test user by email.
3. Complete the verification on the test user's phone.
4. Confirm the work notes and status field update on the Incident and a row appears in Verification Requests.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Connect fails with a permission message | The person connecting does not hold `x_truu_idv.admin` | Grant the role and open a new link |
| Connect says the instance refused an OAuth client-credentials token | The client-credentials grant is off, which is ServiceNow's default | Select **Open the property to turn it on**, save the property as `true`, then select **Connect** again. The linking code has not been used. |
| Connect says the OAuth client could not be saved | The application picker is set to a scoped app | Switch the application picker to **Global** and select **Connect** again |
| Connect says TruU has not been updated for this version of the app | The app is newer than the TruU service it reached | Contact TruU support before connecting |
| Connect reports HTTP 401 | The link expired (15 minutes) or was already used | Generate a new connect link |
| Connect reports HTTP 404 | The API base URL property was changed | Clear it so the default is used |
| Agents do not see Verify Identity | The app is not connected, the agent lacks `x_truu_idv.agent`, the app or that record type is turned off in settings, or the record has no caller (Caller on Incident, Opened for on Interaction, Requested for on Requested Item) | Check each in turn |
| Verify Identity stopped working after an upgrade | Upgrading the app clears its stored credentials | Generate a new connect link and connect again |
| Test connection fails | TruU cannot deliver to your instance: the instance is unreachable, the app is disabled, its credentials were cleared, or the **TruU Identity Verification** OAuth client or `truu.idv.integration` user was deactivated or changed | Confirm the instance is up and the app is enabled, then reconnect |
| Verification requests return an authorization error | The app's credentials no longer match TruU (Test connection does not check this direction) | Generate a new connect link and connect again |
| A result never reached the ticket | Your instance was unreachable when the event was sent | Check the result in the help desk app, or run the verification again |
| Flows that use the subflow fail | The subflow was not published after install or upgrade | Publish **TruU: Verify Identity and Wait** |
| SMS is not offered | Allow SMS is off, the caller has no mobile number on file (a business phone is not used), or the number is not in international format (numbers outside North America need a leading +) | The dialog shows the reason. Use email or copy link |
| Caller has no email or phone in the directory | Nothing to deliver to | The agent can copy the link and share it in the existing conversation |

## Known issues

* **Upgrading the app clears its credentials.** After any upgrade, generate a new connect link and connect again, then publish the subflow.
* **Upgrading to 1.1.3 or later needs a reconnect.** Earlier versions authenticated events with a shared secret, which 1.1.3 removes. Connect again to create the integration user and OAuth client; until you do, results don't reach your records.
* **Which use case is used.** The **Verify Identity** action sends **Helpdesk**. Flow Designer content sends the use case you pick: Help desk (Helpdesk), Pre-hire (Onboarding) or Password reset (Credential reset). See [How use cases work](https://docs.truu.ai/idv/use-cases/overview.md#how-a-verification-gets-its-use-case).

## Related pages

> [card] [Solution guide: verified help desk](https://docs.truu.ai/idv/use-cases/help-desk.md)
>
> Roll out verified resets end to end.

> [card] [Creating verification requests](https://docs.truu.ai/idv/help-desk/agent-guide.md)
>
> The agent workflow the app mirrors.

> [card] [Network and allowlists](https://docs.truu.ai/idv/security/network.md)
>
> Every host TruU uses.

> [card] [Permissions and roles](https://docs.truu.ai/idv/admin/team-and-roles.md)
>
> Why the app cannot change your TruU configuration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.