API Client Allow Lists

All API clients have an “allow list” (referred to in Console as a “white list”). 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 endpoint, a note that tells you whether the endpoint respects the allow list of not. For example:

Respects API Client Allow List: Yes

If an endpoint 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 endpoint 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 endpoints in those APIs respect an API client allow list:

Identity Cloud API

Respects the Allow List

Authentication

Most of the Authentication API endpoints ignore the allow list. There are, however, three exceptions:

Not coincidentally, those are the only three endpoints 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 endpoints: 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 endpoints, 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 endpoints for managing flows, field, transactional emails, translations, forms, two-factor authentication messages, and so on. These endpoints all work regardless of your IP address.

Sometimes

Custom Provider 

The Custom Provider endpoints all ignore the API client allow list. That’s primarily because these endpoints use token-based authentication rather than an authentication process based on API clients.

No

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).

Yes

Legacy Client and Settings 

All the Legacy Client and Settings endpoints respect the API client allow list.

Yes

OpenID Connect, OAuth 2, and Hosted Login 

Like Custom Providers, these endpoints 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.

No

SIEM Event Delivery

The SIEM (Security Information and Event Management) APIs ignore all API client allow lists.

No

Social 

The Social API endpoints 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.

No

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.

No