API Reference

/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]
}
FieldDescription
app.nameName of the application requesting authorisation with the SAFE Launcher.
app.idUnique 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.versionVersion of the application (to be passed as a string).
app.vendorVendor name of the application.
permissionsList 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

{
  token: String,
  permissions: Array[String]
}
Unauthorized
Fields are missing
FieldDescription
tokenJWT 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.
permissionsList of permissions approved by the user.

Examples

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);
Language
Click Try It! to start a request and see the response here!