How to Add a Trusted Domain

Security requirements vary based on a number of factors. For example, developers are provided options on how to go about implementation. Developers can choose between authentication types regarding developer access to our APIs and SDKs.  Another option to improve overall security with our APIs is how to mark a domain as trusted, which is the topic of this post.

What is a Trusted Domain?

Put simply, a trusted domain is considered an acceptable source for making API calls with your credentials. By adding one or more trusted domain names, a developer is establishing where API calls can be trusted from. To phrase it another way, if a trusted 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 list of trusted domains, the call will fail.

Managing Trusted Domains

Trusted domains 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:

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

Once the decision is made to add a trusted domain, 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.