ServiceNow

The ServiceNow auth provider enables tools and agents to call ServiceNow APIs on behalf of a user.

What’s documented here

This page describes how to use and configure ServiceNow auth with Arcade.

This auth provider is used by:

• The Arcade ServiceNow MCP Server, which provides pre-built tools for incidents, changes, catalog requests, knowledge articles, and the CMDB
• Your app code that needs to call ServiceNow APIs
• Or, your custom tools that need to call ServiceNow APIs

Create a ServiceNow OAuth app

Creating the OAuth client requires the oauth_admin, mi_admin, or admin role on the instance. Zurich and later register OAuth clients through Machine Identity Console. Earlier releases use Application Registry.

Get your ServiceNow instance URL

Your instance URL is the host your instance’s REST APIs are served from, in the form https://your-instance.service-now.com. For example, if your instance is acme-inc, your instance URL is https://acme-inc.service-now.com.

Set the ServiceNow instance URL secret

Set the SERVICENOW_INSTANCE_URL secret in the Arcade Dashboard:

• Click the Secrets section in the Arcade Dashboard left-side menu.
• Click the Add Secret button.
• Enter SERVICENOW_INSTANCE_URL as the secret ID.
• Enter your instance URL as the secret value.
• Click the Create button.

The value accepts a bare instance name (acme-inc), a host (acme-inc.service-now.com), or a full URL (https://acme-inc.service-now.com). Arcade normalizes all three to the same origin.

Configuring ServiceNow auth

Using the Arcade ServiceNow MCP server

The Arcade ServiceNow MCP Server provides tools to search and update work records, order catalog items, read knowledge articles, and explore the CMDB.

Every call runs as the authorizing ServiceNow user and honors that user’s roles and ACLs, so a tool returns only what that user could see or change in the ServiceNow UI.

Calling ServiceNow APIs directly

Use the ServiceNow auth provider to get a user authorization token and call ServiceNow API endpoints directly, without the use of any tools. See How Arcade helps with Agent Authorization to understand how this works.

Prerequisites

1. Create an Arcade account
2. Get an Arcade API key.
3. Set the ARCADE_API_KEY environment variable (export ARCADE_API_KEY=your-api-key on Bash, $env:ARCADE_API_KEY="your-api-key" on PowerShell).
4. Make sure to have Python 3.10+ or Node.js 18+ installed.

import requests
from arcadepy import Arcade
 
client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
 
user_id = "[email protected]"
instance_url = "https://acme-inc.service-now.com"
 
auth_response = client.auth.start(
    user_id=user_id,
    provider="servicenow",
    scopes=["useraccount"],
)
 
if auth_response.status != "completed":
    print("Click this link to authorize: " + auth_response.url)
    auth_response = client.auth.wait_for_completion(auth_response)
 
token = auth_response.context.token
 
response = requests.get(
    instance_url + "/api/now/table/incident",
    headers={"Authorization": "Bearer " + token},
    params={"sysparm_limit": 5, "sysparm_query": "active=true"},
)
 
print(response.json())

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
 
const userId = "[email protected]";
const instanceUrl = "https://acme-inc.service-now.com";
 
let authResponse = await client.auth.start(userId, "servicenow", {
  scopes: ["useraccount"],
});
 
if (authResponse.status !== "completed") {
  console.log("Click this link to authorize: " + authResponse.url);
  authResponse = await client.auth.waitForCompletion(authResponse);
}
 
const token = authResponse.context.token;
 
const response = await fetch(
  instanceUrl + "/api/now/table/incident?sysparm_limit=5&sysparm_query=active=true",
  { headers: { Authorization: "Bearer " + token } },
);
 
console.log(await response.json());

Using ServiceNow auth in custom tools

If the Arcade ServiceNow MCP Server does not meet your needs, you can author your own custom tools that interact with ServiceNow APIs.

Use the OAuth2() auth class to specify that a tool requires authorization with ServiceNow. The id must match the ID of the provider you created, and context.get_auth_token_or_empty() returns the user’s ServiceNow token:

from typing import Annotated, Any
 
import httpx
from arcade_mcp_server import Context, tool
from arcade_mcp_server.auth import OAuth2
 
 
@tool(
    requires_auth=OAuth2(id="servicenow", scopes=["useraccount"]),
    requires_secrets=["SERVICENOW_INSTANCE_URL"],
)
async def get_active_incidents(
    context: Context,
) -> Annotated[dict[str, Any], "Active incidents from ServiceNow"]:
    """Get active incidents from ServiceNow."""
    token = context.get_auth_token_or_empty()
    instance = context.get_secret("SERVICENOW_INSTANCE_URL")
    url = f"https://{instance}.service-now.com/api/now/table/incident"
    headers = {
        "Authorization": f"Bearer {token}",
        "Accept": "application/json",
    }
    params = {"sysparm_query": "active=true", "sysparm_limit": 10}
 
    async with httpx.AsyncClient() as client:
        resp = await client.get(url, headers=headers, params=params)
        resp.raise_for_status()
 
        return {"incidents": resp.json().get("result", [])}

Troubleshooting

• The provider doesn’t show up for your tools: it was created in a different Arcade project. The provider is project-scoped. Confirm the active project with arcade project set your-project-id and check the provider exists there.
• Authorization succeeds but every tool call returns 403: the authorizing user lacks the roles needed for the table the tool reads or writes. Re-authorize as a user with broader access, or adjust the ACLs on the target table.
• Tools report that the instance URL is not configured: the SERVICENOW_INSTANCE_URL secret is missing, or set in a different project than the one running the tools.
• Redirect mismatch errors: the redirect URL on the ServiceNow integration doesn’t match the one Arcade generated. Copy it again from the provider in the Arcade Dashboard.
• A setting change doesn’t seem to take effect: existing tokens don’t retroactively pick up changes to the OAuth integration. Revoke the existing grant for the affected user and re-authorize to get a fresh token.

Next steps

• Explore the Arcade ServiceNow MCP Server tool reference.
• Connecting to a ServiceNow-hosted MCP server instead? See Connect a ServiceNow Hosted MCP Server.