App Authentication

Credentials

We'll create your Organisation in our Sandbox environment so you can create Apps & Locations to use during development.

Authentication

Each App you develop has its own Client ID and Client Secret for use with JWT Bearer tokens. Requests to all API resources use JSON Web Tokens for authentication (see JWT.io for more info), which you create using your supplied Client Secret in combination with the Client ID.

You will need to regenerate the tokens frequently as the Doshii API ensures the tokens have not expired.

The token should be encrypted using default hash algorithm (HS256) with the payload:

"clientId": The Client ID of the App retrieved from the Doshii dashboard.
"timestamp": The current timestamp in EPOC-Seconds for validating the request expiry time, default is 10 minutes.

There are many implementations of JWT available for each platform .NET, NodeJS, PHP, etc.

C# example of token generation

// Using https://github.com/jwt-dotnet/jwt

var unixEpoch = new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
var now = Math.Round((DateTime.UtcNow - unixEpoch).TotalSeconds);

var payload = new Dictionary<string, object>() {
  { "clientId", "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." },
  { "timestamp", now }
};

var clientSecret = "";
string token = JWT.JsonWebToken.Encode(payload, clientSecret, JWT.JwtHashAlgorithm.HS256);

Node.js example of token generation

const jwt = require('jwt-simple');
const moment = require('moment');

const payload = {
  clientId: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9....',
  timestamp: moment().unix()
};

const clientSecret = "";
const token = jwt.encode(payload, clientSecret, 'HS256', {});

HTTP Headers

Once your token has been generated, it needs to go into your request header. Typically requests have 3 required headers:

"content-type": "application/json",
"doshii-location-id":"Abc123",
"authorization":"Bearer Rhczkb3JW5nRlY.ITsalOSJKlmw921....." 

• Content-Type
  • Doshii is a JSON API so this should always be set to "application/json"
• Doshii-Location-Id
  • This is the Hashed Location Id of the Location you are attempting to communicate with
• Authorization
  • Always prefixed with Bearer followed by your JWT for the request

Deprecated Authentication Model

For those of you who previously developed against the Doshii Partner API, you will have remembered using HTTP Basic Auth. This authentication model has been deprecated and replaced with more secure JWT bearer tokens, which more closely aligns with the Doshii POS API.

Those currently using Basic Auth to authenticate will continue to work, however, we will be reaching out to have the integration migrated over to the more secure JWT bearer tokens authorisation model in the near future.