API client allow lists

All API clients have an “allow list” (referred to in Console as a “Whitelist”). Allow lists specify the IP addresses that can use the client to make API calls. For example, the following API client has the allow list 192.168.0.0/20:

That means that any IP address within the range 192.168.0.1 through 192.168.15.254 can use this client to make API calls. What if your IP address is 192.168.44.44 and you try to use this client to make an API call? In many cases, that API call is going to fail with an error similar to this:

{
  "error": "client_permission_error",
  "request_id": "72gnhpkttcjgc3ns",
  "error_description": "the provided client does not have authorization for this action",
  "stat": "error",
  "code": 403
}

You might have noticed, however, that we said that in many cases your API call is going to fail if your IP address isn’t on the allow list. However, in other cases, the API simply ignores the allow list; that’s especially true for the newer Identity Cloud APIs (for products such as Hosted Login, Webhooks v3, and Custom Providers) that use token-based authentication instead of Basic authentication (in which the client ID and the client secret of an API client are function as the username and password).

This can create some confusion: you create an allow list expecting to block any IP addresses that aren’t on the list only to find out that the API client can be used no matter what your IP address happens to be, and regardless of whether it’s on the allow list or not on the allow list. To help minimize this confusion, we’ve added a note to the documentation for each API operation, a note that tells you whether the operation respects the allow list of not. For example:

Respects API Client Allow List: Yes

If an operation respects the allow list (i.e., the preceding answer is Yes) that means you can only leverage that API client if you IP address is on the list. If the operation doesn’t respect the allow list that means that the allow list is ignored and that you can leverage the API client from any IP address.

The following table lists the main categories of Identity Cloud REST APIs, and tells you whether or not the operations in those APIs respect an API client allow list:

Identity Cloud API	Respects the Allow List
Authentication Most of the Authentication API operations ignore the allow list. There are, however, three exceptions: /access/getAuthorizationCode; /access/getAccessToken; and /oauth/token. Not coincidentally, those are the only three operations that require Basic authentication, and require you to specify the client ID and client secret of an API client. If the specified API client has an allow list, that allow list is respected by these three operations: they won’t run unless your IP address is on the allow list.	Sometimes
Configuration Two of the major sections of the Configuration API respect the allow list: API Clients and Entity Types. When calling any of those operations, your IP address must be on the allow list. With one or two exceptions, you’re also likely to see this error if your IP address isn’t on the allow list: `{ "message": "Internal Server Error" }` Most of the Configuration APIs fall into the Flow category, which includes operations for managing flows, field, transactional emails, translations, forms, two-factor authentication messages, and so on. These operations all work regardless of your IP address.	Sometimes
Custom Provider The Custom Provider operations all ignore the API client allow list. That’s primarily because these operations use token-based authentication rather than an authentication process based on API clients.	✗
Entity and Entity Type Both the Entity APIs (used for managing user accounts) and the Entity Type APIs (used for managing your entity type databases, user profile attributes, and entity type access schemas) require an IP address found on the API client allow list (assuming, of course, that the API client has an allow list).	✓
Legacy Client and Settings All the Legacy Client and Settings operations respect the API client allow list.	✓
OpenID Connect, OAuth 2, and Hosted Login Like Custom Providers, these operations use token-based authentication and, as a result, don’t interact with API clients (and, by extension, with API client whitelists). Note that all OpenID Connect login clients (required for user logins and registrations) must be associated with an API login client. However, users will always be able to login and register regardless of whether or not the associated API client has an allow list.	✗
SIEM Event Delivery The Security Information and Event Management APIs ignore all API client allow lists.	✗
Social The Social API operations don’t respect the API client allow list, in large part because the Social APIs don’t even reference an API client. Instead, authorization and access is controlled by using a Social Login application API key.	✗
Webhooks v3 Webhooks v3 doesn’t respect the API client allow list. Like Custom Providers and like the OpenID APIs, Webhooks v3 relies on token authentication rather than Basic (and API-client-based) authentication.	✗