/auth

POST https://example.com/auth

Any application that wants to access API endpoints that require authorised access must receive an authorisation token from SAFE Launcher.

Reading public data using the DNS API does not require an authorisation token. All other API endpoints require authorised access.

The application will initiate the authorisation request with information about the application itself and the required permissions. SAFE Launcher will then display a prompt to the user with the application information along with the requested permissions. Once the user authorises the request, the application will receive an authorisation token. If the user denies the request, the application will receive an unauthorised error response.

Request Header

Content-Type: application/json

Request Payload

{
  app: {
    name: String,
    id: String,
    version: String,
    vendor: String
  },
  permissions: Array[String]
}

Field	Description
app.name	Name of the application requesting authorisation with the SAFE Launcher.
app.id	Unique ID for the application. The ID should be unique among the applications provided by the vendor. If the ID (or the vendor name of the application) changes, the application data will be lost. Likewise, if multiple applications of the same vendor use the same the ID, then those applications will share the same application folder.
app.version	Version of the application (to be passed as a string).
app.vendor	Vendor name of the application.
permissions	List of permissions requested by the applications. An empty array should be passed if no permissions are required. Alternatively, the list of permissions can be passed as a string. Permitted permission keys: SAFE_DRIVE_ACCESS.

Response

200

{
  token: String,
  permissions: Array[String]
}

401

Unauthorized

400

Fields are missing

Field	Description
token	JWT token that has to be used in all the authorised API calls. This token has to be passed in the Authorization header field for making authorised API calls.
permissions	List of permissions approved by the user.

Examples

Nodejs

var request = require('request');

var endPoint = 'http://localhost:8100/auth';

// authorisation payload
var payload = {
  "app": {
    "name":"Sample Application",
    "id":"com.maidsafe.sample",
    "version":"0.0.1",
    "vendor":"MaidSafe"
  },
  "permissions": [
    "SAFE_DRIVE_ACCESS"
  ]
};

var onResponse = function(err, response, body) {
  if (err) {
    return console.error(err.message);
  }
  if (response.statusCode === 401) {
    return console.error('Failed to authorise');
  }
  console.log('Auth token', body.token);
};

request.post(endPoint, {  
  json: true,
  body: payload
}, onResponse);