Skip to content

Server to Server Validation Approach

The How It Works section outlines the concept of the server to server approach. There are a number of distinct steps to use this approach:

  1. Use the DeviceAssure client library to collect device data. The data is provided to the calling client application.
  2. The collected data should be transmitted in a secure manner to a suitable server.
  3. The server makes a request to the DeviceAssure service with the collected data and client HTTP headers.
  4. The validation results are returned directly to the server and not to the client.

Details on how to call the DeviceAssure REST API for device validation is described in the following sections.

Calling the DeviceAssure REST API

DeviceAssure provides a simple REST API that may be used to validate the data collected by the DeviceAssure client libraries. The following sections assume that the data has already been collected by the client and securely transmitted to a suitable server.

The collected device data must be sent as a POST request along with a number of client HTTP headers.

API URLs

The DeviceAssure service is geo-distributed and will automatically use the nearest API server for a request. There are a number of API endpoints provided for fallback purposes.

The API endpoint URLs should be called in the order specified. If an error or timeout occurs then api2 should be called and finally api3. Please see the Error Codes section.

Priority Endpoint
Primary https://api1.devicevalidation.io/check
Fallback 1 https://api2.devicevalidation.io/check
Fallback 2 https://api3.devicevalidation.io/check

A licence key must be included in a URL parameter called licence. This key is provided as part of the on-boarding process. The request will not be accepted if the provided licence key is not valid.

An example of this is below:

https://api1.devicevalidation.io/check?licence=<LICENCE_KEY>

Required HTTP Headers

The client application sends a number of HTTP headers along with the device data. Some of these are required by the DeviceAssure Service and should be extracted and sent along with the device data to the DeviceAssure REST API. These HTTP headers must be prefixed with DV-.

Android Library HTTP Headers

Forwarded Client HTTP Headers

These HTTP headers must be extracted from the client request and forwarded to the DeviceAssure API with the DV- prefix.

HTTP Header Required Description Example
DV-client-ip Yes The client IP address. Commonly found in the client-ip header but may be present in other headers depending on your server configuration. DV-client-ip: 89.101.149.145
DV-user-agent Yes The client user-agent header. DV-user-agent: Mozilla/5.0 (Linux; Android 4.0.4; ...)

Additional Required HTTP Headers

These HTTP headers should be included directly in the request to the DeviceAssure API.

HTTP Header Required Description Example
accept Yes The accept header for the response format. accept: application/json;charset=UTF-8

Web Library HTTP Headers

In addition to DV-client-ip, all client request HTTP headers must be included, prefixed with DV-.

Original HTTP Header Send As Example
accept-language DV-accept-language DV-accept-language: en-US,en;q=0.9
accept-encoding DV-accept-encoding DV-accept-encoding: gzip, deflate, br
user-agent DV-user-agent DV-user-agent: Mozilla/5.0 ...
(all others) DV-{header-name} Prefix all client HTTP headers with DV-

Note: All client request HTTP headers must be forwarded and prefixed with DV-.

For improved request tracing, reliability, and support, the following optional headers can be included. The values are extracted from the payload object returned by the client library.

Header Value Description
DV-DeviceAssure-ID payload.info.requestId Unique identifier for this verification session, useful for correlating retries across failover URLs
DV-DeviceAssure-Variants payload.info.variants Session variant identifiers from the client library
DV-DeviceAssure-Version payload.info.version Version of the client library that collected the data
DV-DeviceAssure-Attempt 0, 1, 2 Tracks which API endpoint is being called. Start at 0 for the primary endpoint, increment on each failover 
// Extract from the payload received from the client
const headers = {};
headers['DV-DeviceAssure-ID'] = payload?.info?.requestId;
headers['DV-DeviceAssure-Variants'] = payload?.info?.variants;
headers['DV-DeviceAssure-Version'] = payload?.info?.version;

let attempt = 0;
for (const url of deviceAssureApiUrls) {
  headers['DV-DeviceAssure-Attempt'] = attempt;
  // ... make the API call with these headers
  attempt++;
}

Making the Request

The data collected from the end user device must be sent in its entirety, in JSON format, within the body of a POST request.

Request Requirements:

Component Requirement
Licence key Include as URL parameter ?licence=<LICENCE_KEY>
Client HTTP headers (Android) Include DV-user-agent and DV-client-ip
Client HTTP headers (Web) Include all client HTTP headers prefixed with DV-
Body Full unaltered JSON data collected from the client device
Method POST

Sample Request

A sample DeviceAssure Android library request is provided below. The body of this request is for example purposes only. In practice, the full unaltered JSON data collected from the client device is required.

POST /check?licence=<LICENCE_KEY> HTTP/1.1
Host: api1.devicevalidation.io
DV-user-agent: <client-user-agent>
DV-client-ip: <client-ip-address>
accept: application/json;charset=UTF-8
content-length: <length>

{
  "info": {
    "version": "2.0.3",
    "date": "2020-04-04T15:50+0000"
    ... more data ...
  },
  "data": {
    "build": {
      "manufacturer": "Samsung",
      "model": "GT-N9500",
      ... more data ...
    },
    "gpu": {
      "renderer": "PowerVR SGX544 MP3"
    }
    ... more data ...
  }
}

Further information and example code can be found in the Android Server to Server and Web Server to Server guides.

Validation Response

The DeviceAssure REST API will return a validation result back to the calling server. This response is in JSON format. Please see the Service Responses section for further details.

See Also