Using the SDK Token

Distil provides your application with the token through the getToken call. Your application must always perform the getToken call immediately before any request to the API and the returned token should be appended as an HTTP header. Your application should never store the token, since when the token expires the SDK will transparently perform the authentication steps again upon the next getToken call.

Handle Error States

The getToken method can fail to fetch a token due to various reasons such as lack of network connectivity, internal errors etc. The application must handle these errors with a similar strategy as for the connections to the API server. For example, the application shows a dialog to the user requesting them to check their connectivity status.

For non-network related errors, the application should continue as normal, without a token. This ensures proper function in the case of the Distil server is bypassed for some reason. We also recommend using a circuit-breaker that backs off from calling getToken when in prolonged error state.

Response Codes

When your application makes API calls with the token added as a header, the Distil server responds with either a 200 (OK) or a 456 (BLOCKED) code. The 200 response means the request is allowed by Distil. Your API server sends back the payload to your application. The 456 response means the request triggered a treat violation and the security setting configured in the Distil Portal is set to drop the request for the specific threat violation.

Violation Types

The table below lists the possible violations you can customize behavior for in the Distil Portal.

Violation Description
No Distil Identifier

The request did not have a token added as a HTTP header.

The Distil Portal reports this threat as "Missing Unique ID".

Bad Client

The application issuing the request was executed under suspicious circumstances. This typically occurs when the request is made from an application simulator/emulator or an automation tool.

The Distil Portal reports this threat as "Bad Client Automation Tools".

Invalid or Expired Token

The request’s authentication token is invalid or expired. This typically occurs when a request fails the SDK challenge or fails the token integrity check.

The Distil Portal reports invalid token violations as "Invalid Identifier Test Results" and reports expired tokens as "Identifier Tampering or Expiration".


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