Creating Custom Tokens

Custom token settings let you authenticate API requests made from your mobile application using a custom authentication token (rather than one that is Distil-generated). This is especially useful when protecting your mobile apps via the Distil SDK.

Prior to fully integrating your mobile app with our SDK and having users install your Distil-protected version, you can configure a custom token and have Distil immediately start protecting the app.

NOTE: Please contact your Distil implementation engineer and request to enable custom token settings.

To access Custom Token settings:

  1. Log in to the Distil Portal.

  2. Click API Security on the top banner menu, then select Web & Mobile App API.

  3. Select a domain from your Web & App API Domains dashboard.

  4. Click Settings on the banner menu.

  5. Click Set Custom Token.


Configuring Custom Tokens

Distil currently allows up to two custom tokens: a primary (required) and a secondary (optional). When we inspect an API request, we look for the specific Token Name in the configured Token Location (query string, parameter, header, cookie, body).

If we do not find the Primary Token in its configured Token Location, then we look for the Secondary Token in its configured Token Location.

To configure custom tokens:

  1. Enter the Token Name. This is the specific value Distil looks for when inspecting an API request. For example, api_nameof_token and api-alternatenameof-token.

    NOTE: The Token Name is case insensitive. It also must be 1 – 45 characters long and may only contain letters, numbers, underscores (_), and hyphens (-).


  2. Select the specific Token Location where Distil should look for the Token Name.


  3. Select the appropriate threat response from the dropdown menu.

    • Monitor – Distil logs the request with the associated violation, but does not block or impede the request from accessing your API.

    • Drop – Distil serves a drop page to the requester, along with the associated violation to indicate their API access has been blocked.

  4. Click Save.


NOTE: You can click the Remove_Custom_Token__small_.png  icon associated with the token to remove it, if necessary.


One you have configured your custom token, add a new API path or edit an existing API path, then set the Identity Provider of the Custom Token.

Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request