Advanced API Access Controls: Auth Scope, OAuth Entity Linking, and MIAC (Part 2)

[PrabhuShan]

In Part 1, we covered the fundamentals of REST API Access Policies — how to restrict APIs by authentication method, IP, role, and group. But what happens when those fundamentals aren't enough? What if you need to restrict an API to a specific OAuth application rather than all OAuth apps? Or ensure an integration user can only access the Import Set API and nothing else? That's where advanced access controls come in. This post covers the tools you need when basic policy conditions don't give you enough precision.

---

When Do You Need Advanced Controls?

REST API Access Policy conditions (authentication method, IP, role, group) apply broadly — they match all requests that meet the criteria. But sometimes you need to be more targeted:

Scenario	Basic Policy Enough?	What You Need
"Only allow OAuth authentication for this API"	✅ Yes	API Access Policy
"Only allow OAuth from my CRM integration, not other OAuth apps"	❌ No	OAuth Entity Linking
"My OAuth app should only access APIs explicitly assigned to it"	❌ No	Enforce Token Restriction
"My integration user should only access Import Set API, nothing else"	❌ No	MIAC (Machine Identity Access Controls)

The key insight: basic policies control the conditions for access, but they don't distinguish between which specific app or user is making the request. Advanced controls fill that gap.

---

Two Types of Identities, Two Sets of Controls

Before diving in, it helps to understand that API consumers fall into two categories, and each has its own set of advanced controls:

Identity Type	Authentication	Advanced Controls
OAuth Applications	OAuth tokens	Auth Scope (REST API Auth Scope), OAuth Entity Linking, Enforce Token Restriction
Integration Users	Basic Authentication	MIAC (Machine Identity Access Controls)

Let's explore each.

---

Controls for OAuth Applications

What is Auth Scope?

Before exploring the OAuth controls, it's worth understanding Auth Scope (also known as REST API Auth Scope) as a concept. Auth Scope is a mechanism that defines which APIs an OAuth application is allowed to access. You create named scopes, associate APIs to them, and then assign those scopes to your OAuth clients. Think of it as a menu — Auth Scope defines what's on the menu for each OAuth app.

For example, say your instance exposes the Table API, Import Set API, Attachment API, and CMDB API. You could create an Auth Scope called "CRM Integration" and associate only the Table API and Import Set API to it. Any OAuth client assigned this scope can only access those two APIs.

But there's an important default behaviour to understand.

Broadly Scoped vs. Restricted Scope

When configuring an OAuth client, there's a setting called "Allow access only to APIs in selected scope". This controls whether the client follows a strict or permissive model:

When enabled (default for new OAuth clients): The OAuth client can only access APIs that are explicitly associated with its assigned Auth Scope. If an API isn't in the scope, it's blocked — even if the API has no scope association at all.

When disabled (broadly scoped): The OAuth client can access APIs associated with its Auth Scope, and also any API that isn't associated with any Auth Scope. Only APIs explicitly assigned to a different scope are blocked.

Example: Your instance has three APIs — Table API, Import Set API, and Attachment API. Table API and Import Set API are associated with the "CRM Integration" scope. Attachment API is not associated with any scope.

• With "Allow access only to APIs in selected scope" enabled: Your CRM OAuth client can access Table API and Import Set API only. Attachment API is blocked.
• With the setting disabled (broadly scoped): Your CRM OAuth client can access Table API, Import Set API, and Attachment API — because the Attachment API isn't claimed by any scope.

In both cases, the user associated with the OAuth client still needs the appropriate roles and access. Auth Scope is an additional restriction layer, not a replacement for user-level access controls.

How Auth Scope Works with API Access Policies

A common question is: how do Auth Scope and API Access Policies relate to each other?

Think of it this way:

• API Access Policy controls the "how" — under what conditions (authentication method, IP, role, group) can an API be accessed?
• Auth Scope controls the "what" — which APIs is this specific OAuth app allowed to access?

Evaluation order: API Access Policies are evaluated first. If the policy denies the request (wrong auth method, blocked IP, missing role), it's rejected before Auth Scope is even checked. If the policy allows it, Auth Scope is then evaluated to confirm the OAuth app has permission for that specific API. Both must be satisfied for the request to succeed.

Example: You configure your CRM OAuth app with Auth Scope that permits only Table API and Import Set API. Even if the Attachment API has a policy that allows OAuth, this CRM app won't be able to access it — Auth Scope blocks it after the policy check passes.

OAuth Entity Linking: Restricting a Policy to a Specific App

By default, API Access Policies don't distinguish between different OAuth applications. If a policy allows OAuth and the access conditions (IP, Role, Group) are met, any OAuth app gets through.

OAuth Entity Linking changes this. When configuring an Authentication Profile with OAuth or ID Token (Federated Token), you can link it to a specific OAuth entity (application).

• Without linking: Any OAuth app that meets the policy conditions can access the API.
• With linking: Only the linked OAuth app can access the API through that policy. All other OAuth apps are denied.

Example: You have three OAuth integrations — CRM, HRMS, and a mobile app. You want only the CRM integration to access the Customer API. Link the CRM OAuth entity to the Authentication Profile on that API's access policy. The HRMS and mobile app will be denied, even though they authenticate via OAuth.

Enforce Token Restriction: The Strictest Control

Within the OAuth entity configuration, there's a setting called Enforce token restriction (disabled by default). Enabling it adds one more requirement: the API Access Policy must be explicitly linked to this OAuth entity through an Authentication Profile.

Here's the difference:

Without Enforce Token Restriction:

• API Access Policy allows OAuth and conditions are met ✓
• Auth Scope allows the API ✓
• Access Granted ✅

With Enforce Token Restriction enabled:

• API Access Policy allows OAuth and conditions are met ✓
• API Access Policy is explicitly linked to this OAuth entity ✓
• Auth Scope allows the API ✓
• Access Granted ✅

If the second condition fails — even if the policy allows OAuth and Auth Scope allows the API — the request is denied.

When to use this: You want the strictest possible control. Your OAuth app can only access APIs where it's been explicitly configured in both Auth Scope and the API Access Policy. No implicit access, no surprises.

---

Controls for Integration Users

MIAC: Allowlisting APIs for Integration Users

The OAuth controls above don't apply to integration users authenticating with Basic Authentication. For these users, the equivalent control is Machine Identity Access Controls (MIAC). The problem MIAC solves: REST API Access Policies control the conditions for accessing APIs, but they don't restrict which APIs a specific integration user can access. An integration user with the right roles could access any API that permits Basic Auth — Table API, CMDB API, Attachment API, everything. MIAC fills this gap with a deny-by-default model. Once MIAC is enabled for an integration user, all API access is blocked unless explicitly allowed. You then define exactly what the user can do:

• You specify which APIs the user can access
• You specify which tables the user can query through those APIs
• Everything else is denied — regardless of the user's roles, even if the user has the admin role

This is the critical difference from API Access Policies: policies define the conditions under which access is allowed, but MIAC flips the model entirely — nothing is allowed until you say so.

Example: You create an integration user for your monitoring tool that needs to query incidents via the Table API. With MIAC, you restrict that user to only the Table API for the incident table. If someone later tries to repurpose that account to pull HR data from sys_user, the request is blocked.

For more details, see Machine Identity Access Controls

---

Quick Reference: Which Control for Which Identity?

Control	OAuth Applications	Integration Users (Basic Auth)
API Access Policy	✅ Always applies	✅ Always applies
Auth Scope (REST API Auth Scope)	✅ Controls which APIs the app can access	❌ Not applicable
OAuth Entity Linking	✅ Restricts policy to a specific OAuth app	❌ Not applicable
Enforce Token Restriction	✅ Requires explicit policy linkage	❌ Not applicable
MIAC	❌ Not applicable	✅ Deny-by-default; explicitly allows APIs and tables

---

Choosing the Right Control: A Decision Guide

For OAuth Applications:

1. Need to limit which APIs an OAuth app can access? → Use Auth Scope
2. Need to restrict an API to a specific OAuth app? → Use OAuth Entity Linking in the Authentication Profile
3. Need both — the app can only access APIs where it's explicitly configured? → Enable Enforce Token Restriction

For Integration Users (Basic Auth):

1. Need to limit which APIs and tables an integration user can access? → Use MIAC

---

One More Thing: "Advertise All Auth Schemes"

There's one more setting worth understanding, especially if you're managing multiple authentication methods across your APIs. When an unauthenticated request hits a ServiceNow API, the platform sends back a WWW-Authenticate response header telling the client which authentication methods are available. The "Advertise all auth schemes" option controls what goes into that header.

When Enabled

ServiceNow tells the client about all supported methods:

WWW-Authenticate: Bearer realm="ServiceNow"
WWW-Authenticate: Basic realm="ServiceNow"
WWW-Authenticate: Mutual

This helps API clients (Postman, SDKs, API gateways) discover and choose a supported method.

When Disabled

Only the preferred scheme is advertised (typically OAuth):

WWW-Authenticate: Bearer realm="ServiceNow"

The client isn't told that Basic Auth or other methods might also work.

When to Enable

• Multiple client types use different authentication methods
• You want clients to auto-negotiate the method
• You're in a transition phase — migrating from Basic Auth to OAuth

When to Disable

• You want to enforce OAuth — advertising Basic Auth may encourage insecure usage
• You're exposing internet-facing APIs — best practice is to advertise only the strongest scheme
• You want predictable client behavior — some clients pick the first scheme advertised, not the most secure

Important: This setting controls what clients see, not what's actually allowed. It does not enable or disable authentication methods — that's controlled by API Access Policies.

---

Further Reading

• Part 1: Demystifying REST API Access Policies — Learn the fundamentals
• Machine Identity Access Controls — Deep dive into MIAC
• API Access Policy Prioritization — Detailed prioritization logic

---

Have questions about advanced API access controls? Drop them in the comments below!