How to Secure Credentials with a Whitelist

At the end of 2019 we announced the availability of two new authentication types regarding developer access to our APIs and SDKs. These new authentication types were an improvement over the use of APP ID and APP Code. For example, our latest versions of the JavaScript APIs now use an API Key to initialize. In this post, we will cover another option to improve overall security with our APIs - add a domain to a whitelist.

What is a Whitelist?

A whitelist is a list of entities considered to be acceptable or trustworthy. In the context of this blog post, the entities are domains. By whitelisting one or more domain names, a developer is establishing where API calls can be trusted from. To phrase it another way, if a whitelist domain is the source of the API call, the request will be allowed. The contrast is also true - if the source of an API call comes from a domain not found in the whitelist, the call will fail.

Managing a Whitelist

Whitelists are managed in the developer portal where developer credentials are also managed. In the screen capture below, the area in the red rectangle is where one would get started with whitelisting:

As shown above, the default setting is no whitelist is created yet. When there is no whitelist, it means any domain can freely make calls with the associated developer credentials.

Once the decision is made to add a domain to the whitelist, you will see the following options:

With the checkbox now enabled, domain names can be added or removed using the plus and minus buttons. To add a domain, enter domain names with the following format:

• example.com
• www.example.com
• app.example.com

The following examples are *not* valid:

• http://www.example.com
• example.*
• example.com?foo=bar

The first invalid example includes the HTTP protocol which is not needed. The second invalid example makes the assumption that wildcards are supported (they are not). The third invalid example contains a querystring which is not a way to uniquely identify a domain.

You can add up to 20 domains in the list. Note! Once you have entered *any* domain in the list, all *other* sources making requests using your credentials will fail (which is the desired outcome). Also keep in mind it can take up to a full hour for any modifications to the list (including it's creation) to take effect.

Summary

For more information, please check out our tutorial or feel free to watch the brief video below!