The Destination interceptor allows redirecting a request to a new destination based on values contained in environment variables, extra fields of apps or access tokens or by manually inserting a new address.

As it modifies the request destination, it can only be added to the request flow, not the response flow.

Unlike Mediation interceptors, which invoke a new call to a pre-configured destination, this interceptor only changes the destination of an incoming request. It is very useful when, for instance, you wish to test a different backend for a given Plan. In this case, instead of adding it to an API flow, you can insert it into the flow of a plan linked to an API.

Configuring the interceptor

To configure the interceptor, you must choose where the new URL is to be found, as the image below shows. The options are: Environment Variable, Apps, Access Tokens, and Custom.

destination options


This is the easiest way of attributing a new address to the request.

There are two tabs where you can insert the URL: Entire URL and Host. They allow choosing whether the new destination will alter only the host of the request or if it will completely replace the previous URL.

After deciding this, you can insert a valid URL into the the URL field of the tab you choose.

destination custom entire url
destination custom host
When the Host option is chosen, only URLs with protocol and host will be accepted, such as

Environment Variable

Environment Variables are fields which are pre-configured in each environment, allowing variables to have different values for each environment an API is deployed to.

To insert a new destination URL, it must have been registered as the value of an environment variable on the Environments page. Then, on the interceptor’s settings, the name of the variable must be referenced in the field Variable, always including $ to identify the variable.

In the example below, we are referencing the variable $variableName, and the URL is registered as a value on the Environment Variables section of the environment.

destination environment variable1
destination environment variable
In the case of URLs from environment variables, all registered environments on your Manager must contain the variable you reference. Otherwise, the configuration will not be saved.

Apps and access tokens

Both apps and access tokens can contain extra fields, which can store key-value pairs.

To configure the interceptor, the extra field containing the URL as a value must have been registered on the Apps or Access Tokens pages and, then, you must reference the extra field on the interceptor’s settings.

Imagine, for example, that we wish to reference an extra field named destinationURL. The image below shows its record in the information of an app or token.

destination extra field

Then, we must reference it on the settings, make sure we choose the correct option of where to retrieve it from (respectively, the images show the settings for apps and access tokens).

destination app
destination token
For the interceptor to work properly you need to register a value with host and path in the extra field linked to the app or access token. If there is no path specified in the extra field, the flow will be correctly directed to the host of the interceptor, but with the path indicated in the target destination. Also, if there isn’t any path specified during the entire flow of your API, the interceptor will normally direct it to the host registered in the extra field.

Things to keep in mind

  • Some fields require valid URLs for a correct redirection of requests. Valid URLs contain: a communication protocol (e.g., https://), a host (e.g., and a path (e.g., /api-manager/apis/v3) creating an URL such as:

  • If the URL inserted is invalid or the variable is not found, the interceptor will continue the call using the original destination and will send a message to the Trace.

Thanks for your feedback!

Share your suggestions with us!
Click here and then [+ Submit idea]