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
{
token: String,
permissions: Array[String]
}
Unauthorized
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
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);