If you've ever wondered how to control who can access your APIs and under what conditions, this blog is for you. We'll walk you through REST API Access Policies — what they are, why you need them, and how to configure them effectively.
This blog content applies to Yokohama, Zurich, and Australia releases. Future releases may introduce changes to REST API Access Policy behavior — always refer to the product documentation for the latest details.
Why Do You Need API Access Policies?
By default, all APIs are accessible using standard authentication methods (OAuth, Basic Auth, mTLS, ID Token). If a user has the necessary permissions to access data through the UI, they can access the same data through APIs as well.
However, you may want stricter controls for API access — enforcing specific authentication methods, restricting to trusted IP ranges, or meeting compliance requirements for programmatic access.
REST API Access Policies let you add an additional layer of control specifically for API access.
You can control:
|
Control |
Description |
Example |
|
Who |
Which roles or groups can access |
Only users with "Admin" role |
|
How |
Which authentication methods are allowed |
OAuth only, no Basic Auth |
|
From Where |
Which IP addresses or ranges are permitted |
Only from corporate network (10.0.0.0/8) |
|
What |
Which APIs, versions, resources, or methods the policy applies to |
Only POST requests to /upload on Attachment API v1 |
Understanding Default Behaviour
Before diving into policies, let's understand what happens without any policy configured.
Default Authentication Methods
By default, all APIs accept these authentication methods — no configuration needed:
- ✅ OAuth
- ✅ ID Token (Federated Token)
- ✅ mTLS
- ✅ Basic Auth
These methods are disabled by default and require an explicit policy to enable:
- ⚠️ API Key
- ⚠️ HMAC
How to Restrict Access: A Simple Example
Let's say you want to restrict the Knowledge API to only accept OAuth authentication.
Step 1: Create an Authentication Profile
Create a profile that allows only OAuth.
Step 2: Link the Profile to Your API
Create an API Access Policy for Knowledge API and link the Authentication Profile.
What Happens?
|
|
Before Policy |
After Policy |
|
OAuth |
✅ Works |
✅ Works |
|
ID Token |
✅ Works |
❌ Blocked |
|
mTLS |
✅ Works |
❌ Blocked |
|
Basic Auth |
✅ Works |
❌ Blocked |
The Knowledge API now only accepts OAuth requests.
Common Mistake: Forgetting to Include All Authentication Methods
Here's an important concept to understand when you link a policy to an API, only the authentication methods defined in that policy are allowed — everything else is blocked.
This catches many people when enabling API Key or HMAC authentication.
Scenario: You want to enable API Key based authentication for your Table API along with existing authentication methods.
❌ Wrong approach: You create an API Access Policy and associate only an API Key Authentication Profile.
Result: OAuth, mTLS, and all other methods stop working! Your existing integrations may break.
✅ Correct approach: Associate Authentication Profiles for all the methods you need — OAuth, ID Token (Federated Token), mTLS, Basic Auth, and API Key.
Result: All existing authentication methods continue to work, and API Key is now also enabled.
Remember:
No policy = default access (all default methods work).
Policy linked = restricted access (only what's in the policy works).
Adding More Restrictions with Authentication Policies
Beyond authentication methods, you can add more restrictions by configuring Authentication Policies within the Authentication Profile. These policies can include conditions based on IP, Role, or Group — and can be configured as inclusive (allow only) or exclusive (allow except):
IP Restrictions
Control access based on network location.
Examples:
- Allow only requests from your corporate network (10.0.0.0/8)
- Allow all requests except from specific IP ranges
Role Restrictions
Control access based on user roles.
Examples:
- Allow only users with "Admin" or "API_User" roles
- Allow all users except those with "Guest" role
Group Restrictions
Control access based on group membership.
Examples:
- Allow only members of "Integration_Team" group
- Allow all users except members of "Restricted_Group"
You can combine these for layered security — for example, "OAuth only, from corporate network, with Admin role."
API Access Policy Levels and Precedence
You can create API Access Policies at different levels depending on how broad or specific you want the restrictions to be.
Two Levels of Policies
- Global Level Applies to all APIs in your environment. You can optionally restrict it to specific HTTP methods across all APIs.
Examples:
- Enforce OAuth for all APIs (all methods)
- Enforce OAuth for all GET requests across all APIs (specific method)
- Enforce OAuth for all POST, PUT, DELETE requests across all APIs
- API Level Targets a specific API (e.g., Table API, Knowledge API). Within the API, you can further narrow down by:
- Version — specific version (e.g., v1, v2)
- Method — specific HTTP method (e.g., GET, POST)
- Resource — specific resource (e.g., /incident, /user)
Examples:
- Enforce OAuth for Table API
- Enforce OAuth for Table API v1 (specific version)
- Enforce OAuth for GET requests on Table API (specific method)
- Enforce OAuth and IP restriction for POST requests on Table API v1 (combination)
Precedence: What Happens When Multiple Policies Match?
You can have multiple policies configured at different levels — for example, a Global policy enforcing OAuth for all APIs, and an API-level policy for Table API allowing Basic Auth.
When a request comes in, it might match multiple policies. In such cases, the most specific policy wins.
Example:
- Global policy: Enforce OAuth for all APIs
- API-level policy: Allow OAuth + Basic Auth for Table API
When someone calls Table API with Basic Auth, the API-level policy wins — access is granted. But when they call Knowledge API with Basic Auth, the Global policy applies — access is denied.
The following table shows the complete priority order. Policies at the top have the highest priority and will override policies below them:
|
Priority |
Policy Scope |
Example |
|
Highest |
API + Resource + Method + Version |
Attachment API, /upload resource, POST method, v1 |
|
↑ |
API + Resource + Method |
Attachment API, /upload resource, POST method |
|
↑ |
API + Resource + Version |
Attachment API, /upload resource, v1 |
|
↑ |
API + Resource |
Attachment API, /upload resource |
|
↑ |
API + Method + Version |
Table API, POST method, v1 |
|
↑ |
API + Method |
Table API, POST method |
|
↑ |
API + Version |
Table API, v1 |
|
↑ |
Global + specific Method |
All APIs, POST method only |
|
Lowest |
Global + all Methods |
All APIs, all methods |
How Policy Conditions Work: The Hierarchy
So far, we've covered what API Access Policies can do — restrict by authentication method, IP, role, and group. But how do these pieces fit together? Understanding the internal structure helps you configure policies correctly and troubleshoot when things don't work as expected.
An API Access Policy is not just a single rule — it's a layered structure where multiple conditions can be combined. Here's how it's organized:
API Access Policy
└── Authentication Profiles (one or more)
└── Each Profile contains:
- One Authentication Method (OAuth, API Key, mTLS, etc.)
- Authentication Policies (one or more)
└── Each Policy contains:
- Conditions (one or more)
└── Criteria (IP, Role, Group)
A Real-World Example
Let's say you create an API Access Policy for the Table API with two Authentication Profiles:
Authentication Profile 1: OAuth
- Authentication Policy A: Allow if Role = Admin
- Authentication Policy B: Allow if Group = Engineering AND IP in 10.0.0.0/8
Authentication Profile 2: API Key
- Authentication Policy C: Allow if IP in 192.168.1.0/24
How a Request Gets Evaluated
Request 1: OAuth token with Role = Admin, IP = 8.8.8.8
- Auth method is OAuth → Authentication Profile 1 is selected
- Policy A: Role = Admin? ✅ Yes → Access Granted
Request 2: OAuth token with Role = Developer, Group = Engineering, IP = 10.0.1.50
- Auth method is OAuth → Authentication Profile 1 is selected
- Policy A: Role = Admin? ❌ No
- Policy B: Group = Engineering AND IP in 10.0.0.0/8? ✅ Yes → Access Granted
Request 3: API Key with IP = 192.168.1.100
- Auth method is API Key → Authentication Profile 2 is selected
- Policy C: IP in 192.168.1.0/24? ✅ Yes → Access Granted
Request 4: OAuth token with Role = Viewer, Group = Marketing, IP = 8.8.8.8
- Auth method is OAuth → Authentication Profile 1 is selected
- Policy A: Role = Admin? ❌ No
- Policy B: Group = Engineering AND IP in 10.0.0.0/8? ❌ No
- No policies passed → Access Denied
Summary
|
Concept |
Key Point |
|
Default Access |
APIs are open by default to OAuth, ID Token (Federated Token), mTLS, and Basic Auth |
|
API Key & HMAC |
Requires an explicit policy — include other methods you need or they'll be blocked |
|
Policy Effect |
No policy = default access. Policy linked = only what's in the policy is allowed |
|
Policy Scope |
Global level applies to all APIs; API level can be narrowed by Version, Method, and Resource — the most specific policy wins |
|
Additional Restrictions |
IP, Role, and Group restrictions can be added within Authentication Profiles |
|
Policy Logic |
Profiles, Policies, and Conditions use OR logic — any match grants access. Criteria within a condition use AND/OR as configured |
What's Next?
This blog covered the fundamentals of REST API Access Policies. In Part 2, we'll explore:
- Advanced controls for OAuth applications and integration users
- How Auth Scope and Machine Identity Access Control (MIAC) work alongside API Access Policy
- Choosing the right control based on your identity type
Resources
- REST API Access Policies — Product documentation
