Inbound Web Services — Authentication and Authorization Failures - Support and Troubleshooting

Inbound Web Services — Authentication and Authorization Failures .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Contents Issue — What This Article Covers Quick Triage Two Auth Layers Explained Causes — Diagnosis and Fix 4.1 HTTP 401 — Authentication Failed 4.2 HTTP 403 — Authorization Failed 4.3 HTTP 403 - Application Scope Enforcement 4.4 SOAP — Insert Aborted 4.5 GraphQL — Could Not Process ACLs JWT / OAuth — JWKS URL Configuration Common Misconceptions What to Capture Before Opening a Case Related Articles 1. Issue — What This Article Covers Inbound web service calls that reach the instance but are rejected or produce unexpected results due to authentication or authorization failures.

Symptoms covered:

HTTP 401 Unauthorized — the instance could not authenticate the caller. HTTP 403 Forbidden — the caller authenticated successfully but lacks the required role, ACL, or API access scope. The call returns HTTP 403 with the message User Not Authorized / Access to unscoped api is not allowed - even though the integration user has the correct roles and the call words for other endpoints SOAP request returns SOAPProcessingException: Insert Aborted . GraphQL query returns Could not process ACLs . Call succeeds (200 or 201) but returns an empty body or fewer records than expected due to ACL row-level filtering — see Inbound Web Services — Empty or Incomplete Results for this pattern. How to use this article: Start with the Quick Triage in Section 2. If the request is not reaching the instance at all (no entry in logs), see Inbound Web Services — No Response and Connection Failures instead.

↑ Back to top

2. Quick Triage What you are seeing Most likely cause Go to HTTP 401 on every call Credentials missing, incorrect, expired, or user is inactive / locked Section 4.1 HTTP 401 only on OAuth or token-based calls Token not mapped to a user, expired, or Client Credentials grant misconfigured Section 4.1 HTTP 403 — call authenticated but rejected User missing a required role, ACL, or API access scope Section 4.2 HTTP 403 + "Access to unscoped api is not allowed" Application scope enforcement. Section 4.3 Works as admin, fails as integration user Table or record-level ACL blocking the integration user Section 4.2 403 returned even though the record was created Known ACL response pattern on POST — different article KB2697679 SOAP returns Insert Aborted Business rule, mandatory field, or write ACL blocking the insert Section 4.3 GraphQL returns Could not process ACLs User lacks access to a field or record referenced in the query path Section 4.4 Using JWT Bearer / JWKS URL for inbound OAuth JWKS URL configuration — Zurich and later Section 5 Universal fast check: re-run the failing call while impersonating the integration user in the ServiceNow UI. If the same failure occurs in the UI, the cause is roles or ACLs. If it works in the UI but fails via API, the cause is authentication (the API credential is not resolving to the correct user).

↑ Back to top

3. Two Auth Layers Explained ServiceNow enforces access at two distinct layers. Confusing them is the most common reason 401 and 403 cases take longer than they should.

Layer What it controls Failure code Where to look Processor-level Gates the endpoint itself. SOAP requires a SOAP role ( soap , soap_query , soap_script ). REST requires rest_service . GraphQL requires graphql_api . 401 or 403 User roles in sys_user_has_role Table / record-level ACLs Gates which tables and rows the authenticated user can read, write, or delete. Applied after processor-level access is granted. 403, or silent row filtering on 200 Access Control rules in sys_security_acl

↑ Back to top

4. Causes — Diagnosis and Fix 4.1 HTTP 401 — Authentication Failed Signature: the instance returns HTTP 401 before any business logic runs. The log message is typically User Not Authenticated . The request was received but the instance could not resolve it to a valid, active user.

Common causes:

Incorrect or expired Basic Auth credentials (wrong username, wrong password, or password recently changed). The integration user account is inactive, locked out, or password-expired. An OAuth Client Credentials token that is not mapped to a user record — Client Credentials grants require a configured user to act as. A request relying on SSO or external authentication sent to an endpoint that expects a local credential. Adaptive Authentication or REST API Access Policies blocking the request based on IP, time, or device. Certificate-Based Authentication (CBA) misconfigured or the client certificate not presented. Fix:

Confirm the credential is correct and the user account is Active, not locked, and not password-expired. Navigate to User Administration → Users and inspect the integration user record. For OAuth, verify the token resolves to a user. Review the OAuth token in System OAuth → Manage Tokens and confirm a user is mapped. Review the corresponding entry in Transaction Logs (syslog_transaction) to see how the request was authenticated and where it failed. Confirm the authentication profile in Authentication Configuration (sys_auth_profile) . If Adaptive Authentication is active, check whether the calling IP or context matches a policy that is blocking the request. Related: KB1703578 — "User Not Authenticated" accessing a Scripted REST API via a local user account · KB0745184 — Client Credentials OAuth token generates "User Not Authenticated" on an inbound web service call

↑ Back to top

4.2 HTTP 403 — Authorization Failed Signature: the request authenticated successfully but the instance returns HTTP 403 Forbidden. Common log messages: Not Authorized , Missing required api access scope: , Insufficient rights .

Common causes:

The user is missing a role required by a table or record ACL. An OAuth application has not been granted the required API access scope for the endpoint being called. The request targets a table protected by a write or read ACL that the integration user does not satisfy. On Zurich and later: service or integration accounts can no longer retrieve elevated or restricted roles (for example maint or security_admin ) through the Table API. If a call began failing after an upgrade to Zurich or later and previously retrieved role data, this is the likely cause. Fix:

Identify the failing operation and confirm the integration user holds the required role. Check User Administration → Users → [integration user] → Roles . Review the applicable ACL rules in Access Control (sys_security_acl) for the target table and operation. For OAuth-based calls, confirm the OAuth application has been granted the missing API access scope in System OAuth → Application Registry . Re-run the call as an admin user. If it succeeds, the cause is definitively roles or ACLs on the integration user — not a platform issue. Related: KB2993111 — "User Not Authorized — Missing required api access scope" on an inbound REST API with OAuth 2.0 · KB0822211 — Uses of activating the OOB "Table API" ACL

↑ Back to top

4.3 403 - Application Scope Enforcement This specific 403 is issued by the application scope enforcement layer, not by an ACL. It fires when the endpoint being called belongs to a scoped application and the requesting context does not carry that application's scope. The caller may be fully authenticated and have the correct roles — the request is blocked before ACL evaluation even occurs.

Common triggers:

Calling a Scripted REST API defined inside a scoped app via Basic Auth or an OAuth token that was not granted that application's scope An OAuth Application Registry entry missing the required application scope in its "Accessible from" setting A service account session running in global scope attempting to call a scoped endpoint Quick distinguisher from a standard 403: The error message body will contain the literal string Access to unscoped api is not allowed . A standard ACL 403 will not include this string

4.4 SOAP — Insert Aborted Signature: an inbound SOAP request to insert a record returns a fault with the message:

SOAPProcessingException: Insert Aborted : Error during insert of

The record was not created. The fault is returned to the caller before the insert was committed.

Common causes:

A Business Rule on the target table called current.setAbortAction(true) based on the inbound data — the error text usually names the aborting rule. A Data Policy or mandatory field was not populated in the SOAP request payload. A write ACL on the target table denied the insert for the integration user. Fix:

Read the fault text carefully — it usually names the Business Rule that aborted the insert. Locate that rule under System Definition → Business Rules and review its abort condition. Confirm the SOAP payload populates all mandatory fields on the target table. Navigate to the table definition and check which fields have Mandatory set to true. Verify the integration user passes the write ACLs on the target table by running an insert as that user in the UI. ↑ Back to top

4.5 GraphQL — Could Not Process ACLs Signature: a GraphQL query or mutation fails with:

GraphQL : Exception encountered processing path: - Could not process ACLs

The path in the message identifies the specific field or operation where the ACL check failed.

Common causes:

The authenticated user lacks read or write access to the field or record referenced by the path. An ACL on the underlying table denies the operation for this user. The GraphQL schema exposes a field the integration user is not entitled to access. Fix:

Read the path in the error message to identify the field or operation that failed. Confirm the integration user's roles satisfy the relevant rules in Access Control (sys_security_acl) for that field and table. Review the schema definition in GraphQL API (sys_graphql_schema) to confirm the field is intended to be accessible to the integration user. ↑ Back to top

5. JWT / OAuth — JWKS URL Configuration Starting with the Zurich release, ServiceNow supports using a JWKS URL (JSON Web Key Set) for inbound JWT Bearer authentication instead of manually uploading and mapping certificates. This simplifies configuration when a third-party Identity Provider (IdP) is issuing JWT tokens for inbound integrations.

What it does: the IdP publishes a set of public keys at a well-known JWKS URL. ServiceNow retrieves those keys automatically and uses them to validate the signature of incoming JWT tokens. You paste the URL directly into the configuration — no manual certificate upload or key mapping required.

Configuration steps:

In the filter navigator, open Inbound Integrations . Click New Integration and select OAuth JWT Bearer Grant . In the JWKS URL (JSON Web Key Set) field, paste the JWKS URL from your Identity Provider. Copy the JWKS URL from the IdP's documentation or well-known configuration endpoint (typically https:// /.well-known/jwks.json ). Note: JWKS URL support for the inbound JWT Bearer grant type is available starting with the Zurich release. On earlier releases, certificates must be uploaded and mapped manually. ↑ Back to top

6. Common Misconceptions "An API key bypasses ACLs."

No. An API key authenticates the call as the user mapped to that key. That user is still subject to all processor-level and table/record-level ACLs. The API key is an authentication mechanism, not an authorization bypass.

"If it works as admin, the API is broken for everyone else."

No. Admin users bypass most ACLs. A call that succeeds as admin but fails as the integration user almost always indicates the integration user is missing a role or ACL grant — this is a configuration issue, not a platform bug.

"The integration worked yesterday — nothing changed."

Common triggers that are easy to miss: a scheduled password expiry, a role removed during a user audit, an ACL added as part of a security hardening change, or a platform upgrade that tightened role restrictions (particularly Zurich and later, which restricts retrieval of elevated roles via the Table API).

"A 403 always means a permissions problem on the record."

Not always. A 403 can also mean the OAuth application is missing an API access scope, the endpoint role is absent, or — in one specific pattern — the operation actually succeeded but the ACL prevented the response from being assembled. See KB2697679 for the POST-returns-403-on-success pattern.

↑ Back to top

7. What to Capture Before Opening a Case If self-diagnosis does not resolve the issue, gather the following before opening a support case.

The exact request — full URL, HTTP method, authentication method used, and the full response including status code and body (sanitize credentials before sharing). Time of failure to the second, with timezone (UTC preferred). Integration user — username and the roles currently assigned to that user. Transaction Log entry — the matching record from syslog_transaction for the failing call, including the authenticated user field and response code. Admin re-run result — confirm whether the same call succeeds when made as an admin user. This single data point separates auth issues from platform issues. Recent change context — role changes, ACL modifications, OAuth scope changes, or platform upgrade in the last 30 days. For 403 on OAuth calls: the OAuth application name and the scopes currently granted to it. ↑ Back to top

8. Related Articles Inbound Web Services — Troubleshooting Guide (hub) Inbound Web Services — No Response and Connection Failures Inbound Web Services — Rate Limits and Throttling Inbound Web Services — Empty or Incomplete Results KB2697679 — POST returns 403 although operation succeeded KB1703578 — "User Not Authenticated" accessing a Scripted REST API via a local user account KB0745184 — Client Credentials OAuth token generates "User Not Authenticated" KB2993111 — Missing required API access scope on inbound REST with OAuth 2.0 KB0822211 — Uses of activating the OOB Table API ACL ↑ Back to top