Advanced APIcast Configuration

SaaS On-premises 2.0
This section covers the advanced settings option of 3scale's API gateway in the staging environment.

Define a secret token

For security reasons, any request from 3scale's gateway to your API backend will contain a header called X-3scale-proxy-secret-token. You can set the value of this header in Authentication Settings on the Integration page.

Proxy secret token

Setting the secret token will act as a shared secret between the proxy and your API so that you can block all API requests that do not come from the gateway if you so wish. This gives an extra layer of security to protect your public endpoint while you're in the process of setting up your traffic management policies with the sandbox gateway.

Your API backend must have a public resolvable domain for the gateway to work, so anyone who might know your API backend could bypass the credentials checking. This should not be a problem because the API gateway in the staging environment is not meant for production use, but it's always better to have a fence available.


The API credentials within 3scale are always user_key or app_id/app_key depending on the authentication mode you're using (OAuth is not available for the API gateway in the staging environment). However, you might want to use different credential names in your API. In this case, you'll need to set custom names for the user_key if you're using API key mode:

Custom user_key

or for the appid and appkey:

Custom app_key/app_id

For instance, you could rename appid to key if that fits your API better. The gateway will take the name key and convert it to appid before doing the authorization call to 3scale's backend. Note that the new credential name has to be alphanumeric.

You can decide whether your API passes credentials in the query string (or body if not a GET) or in the headers.

Proxy Credentials Location

Error messages

Another important element for a full-fledged configuration is to define your own custom error messages.

It’s important to note that 3scale's API gateway in the staging environment will do a pass through of any error message generated by your API. However, since the management layer of your API is now carried out by the gateway, there are some errors that your API will never see since some requests will be terminated by the gateway.

Custom Error Messages

These errors are the following:

  • Authentication missing: this error will be generated whenever an API request does not contain any credentials. This occurs when users forget to add their credentials to an API request.
  • Authentication failed: this error will be generated whenever an API request does not contain valid credentials. This can be because the credentials are fake or because the application has been temporarily suspended.
  • No match: this error means that the request did not match any mapping rule, therefore no metric is updated. This is not necessary an error, but it means that either the user is trying random paths or that your mapping rules do not cover legitimate cases.

Configuration History

Every time you click on the **Update & Test Staging Configuration** button, the current configuration will be saved in a JSON file. The staging gateway will pull the latest configuration with each new request. For each environment, staging or production, you can see a history of all the previous configuration files.

Note that it is not possible to automatically roll back to previous versions. Instead we provide a history of all your configuration versions with their associated JSON files. These files can be used to check what configuration you had deployed at any moment on time. If you want to, you can recreate any deployments manually.


Setting up the gateway configuration is easy, but still some errors can occur on the way. For those cases the gateway can return some useful debug information that will be helpful to track down what is going on.

To enable the debug mode on 3scale's API gateway in the staging environment you can add the following header with your provider key to a request to your gateway: X-3scale-debug: YOUR_PROVIDER_KEY

When the header is found and the provider key is valid, the gateway will add the following information to the response headers:

X-3scale-matched-rules: /v1/word/{word}.json, /v1
  X-3scale-credentials: app_key=APP_KEY&app_id=APP_ID
X-3scale-usage: usage[version_1]=1&usage[word]=1

Basically, X-3scale-matched-rules tells you which mapping rules have been activated by the request. Note that it is a list. The header X-3scale-credentials returns the credentials that have been passed to 3scale's backend. Finally X-3scale-usage tells you the usage that will be reported to 3scale's backend.

You can check the logic for your mapping rules and usage reporting in the Lua file, in the function extract_usage_x() where x is your service_id.

    local args = get_auth_params(nil, method)
    local m =,[=[^/v1/word/([\w_\.-]+)\.json]=])
    if (m and method == "GET") then
      -- rule: /v1/word/{word}.json --
      params["word"] = m[1]
      table.insert(matched_rules, "/v1/word/{word}.json")
      usage_t["word"] = set_or_inc(usage_t, "word", 1)
      found = true

In this example, the comment -- rule: /v1/word/{word}.json -- shows which particular rule the Lua code refers to. Each rule has a Lua snippet like the one above. Comments are delimited by -- , --[[, ]]-- in Lua, and with # in NGINX.

Unfortunately, there is no automatic rollback for Lua files if you make any changes. However, if your current configuration is not working but the previous one was OK, you can download the previous configuration files from the deployment history.

Deployment history

Extending the gateway

3scale's hosted APIcast is quite flexible, but there are sometimes things that cannot be done because the console interface doesn’t allow it or because of security reasons due to a multi-tenant gateway.

If you need to extend your API gateway, you can always run it locally on your servers (see the APIcast self-managed section to deploy your own API gateway) and point it to the proper service and configuration from your 3scale account.

When you're running the gateway on your servers, you can customize it to enable any feature you might need – NGINX with Lua is an extremely powerful, open-source piece of technology.

We have written a blog post explaining how to augment APIs with NGINX and Lua. Here are some examples that can be done:

  • Basic DoS protection: white-lists, black-lists, rate-limiting at the second level.
  • Define arbitrarily complex mapping rules.
  • API rewrite rules – for example, you might want API requests starting with /v1/* to be rewritten to /versions/1/* when they hit your API backend.
  • Content filtering: you can add checks on the content of the requests, either for security or to filter out undesired side effects.
  • Content rewrites: you can transform the results of your API.
  • Many, many more. Combining the power and flexibility of NGINX with Lua scripting is an awesome combination.