POS Authentication

Your POS' “Vendor API name” and "Vendor key" that should be used for authentication purposes is available via the Dashboard (we'll register your POS in the Live production environment for you).

Vendor Authentication (On-boarding)

When posting to the /organisations and /locations resources "Bearer" authentication is used with your Vendor key sent as part of the authorization header. e.g.:

"content-type": "application/json",
"vendor":"myposco",
"authorization":"Bearer Rhczkb3Jrc3pZXk2ZW5n..."

• Content-Type
  • Doshii is a JSON API so this should always be set to "application/json"
• Vendor
  • This is the API name of your Vendor in Doshii. We use this to verify your identity.
• Authorization
  • Always prefixed with Bearer followed by your Vendor key

Venue Authentication

Requests to all other API resources use JSON Web Tokens for authentication (see JWT.io for more info), which you create using your supplied Vendor key in combination with the “identifier token” of the location you are targeting.

As a Vendor you'll be communicating with Doshii on behalf of a lot of Locations. It's important to ensure the requests are coming from a trusted source and not a malicious one.

You will need to regenerate the tokens frequently.

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

"locationToken": The “identifier token” of the location retrieved from the Doshii dashboard or returned from the post to the /locationsresource.
"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>() {
  { "locationToken", "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." },
  { "timestamp", now }
};

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

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

"content-type": "application/json",
 "vendor":"myposco",
 "authorization":"Bearer Rhczkb3JW5nRlY.ITsalOSJKlmw921....." 

• Content-Type
  • Doshii is a JSON API so this should always be set to "application/json"
• Vendor
  • This is the API name of your Vendor in Doshii. We use this to verify your identity.
• Authorization
  • Always prefixed with Bearer followed by your JWT for the request