{"metadata":{"image":[],"title":"","description":""},"api":{"url":"/auth","auth":"never","examples":{"codes":[]},"method":"post","params":[],"results":{"codes":[{"code":"","status":401,"language":"text"}]},"settings":""},"next":{"description":"","pages":[]},"title":"/auth","type":"endpoint","slug":"auth","excerpt":"Any application that wants to access API endpoints that require authorised access must receive an authorisation token from SAFE Launcher.\n\nReading public data using the DNS API does not require an authorisation token. All other API endpoints require authorised access.\n\nThe 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.","body":"### Request Header\n\n```\nContent-Type: application/json\n```\n\n### Request Payload\n\n```\n{\n  app: {\n    name: String,\n    id: String,\n    version: String,\n    vendor: String\n  },\n  permissions: Array[String]\n}\n```\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"app.name\",\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"Name of the application requesting authorisation with the SAFE Launcher.\",\n    \"1-0\": \"app.id\",\n    \"1-1\": \"Unique ID for the application.\\n\\nThe ID should be unique among the applications provided by the vendor.\\n\\nIf 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.\",\n    \"2-0\": \"app.version\",\n    \"2-1\": \"Version of the application (to be passed as a string).\",\n    \"3-0\": \"app.vendor\",\n    \"3-1\": \"Vendor name of the application.\",\n    \"4-0\": \"permissions\",\n    \"4-1\": \"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.\\n\\nPermitted permission keys:\\nSAFE_DRIVE_ACCESS.\",\n    \"h-2\": \"\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n### Response\n[block:code]\n{\n  \"codes\": [\n    {\n      \"name\": 200,\n      \"code\": \"{\\n  token: String,\\n  permissions: Array[String]\\n}\",\n      \"language\": \"json\",\n      \"status\": 200\n    },\n    {\n      \"code\": \"Unauthorized\",\n      \"language\": \"http\",\n      \"name\": \"401\"\n    },\n    {\n      \"code\": \"Fields are missing\",\n      \"language\": \"http\",\n      \"name\": \"400\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"token\",\n    \"0-1\": \"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.\",\n    \"1-0\": \"permissions\",\n    \"1-1\": \"List of permissions approved by the user.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Examples\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var request = require('request');\\n\\nvar endPoint = 'http://localhost:8100/auth';\\n\\n// authorisation payload\\nvar payload = {\\n  \\\"app\\\": {\\n    \\\"name\\\":\\\"Sample Application\\\",\\n    \\\"id\\\":\\\"com.maidsafe.sample\\\",\\n    \\\"version\\\":\\\"0.0.1\\\",\\n    \\\"vendor\\\":\\\"MaidSafe\\\"\\n  },\\n  \\\"permissions\\\": [\\n    \\\"SAFE_DRIVE_ACCESS\\\"\\n  ]\\n};\\n\\nvar onResponse = function(err, response, body) {\\n  if (err) {\\n    return console.error(err.message);\\n  }\\n  if (response.statusCode === 401) {\\n    return console.error('Failed to authorise');\\n  }\\n  console.log('Auth token', body.token);\\n};\\n\\nrequest.post(endPoint, {  \\n  json: true,\\n  body: payload\\n}, onResponse);\\n\",\n      \"language\": \"javascript\",\n      \"name\": \"Nodejs\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","updates":["56e7fe01e5f8200e003e0bbb","56e7ff816d0d343400093f0f","56e8ebb23a686c0e002f6063","56e8ec26dae96a0e00de0a10"],"order":1,"isReference":false,"hidden":true,"sync_unique":"","link_url":"","link_external":false,"_id":"5721e9c849df4f0e00528342","createdAt":"2016-03-07T18:32:17.857Z","__v":0,"parentDoc":null,"user":"564d9fcd1936752300aa6439","version":{"version":"0.5","version_clean":"0.5.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5721e9c849df4f0e00528320","5721e9c849df4f0e00528321","5721e9c849df4f0e00528322","5721e9c849df4f0e00528323","5721e9c849df4f0e00528324","5721e9c849df4f0e00528325","5721e9c849df4f0e00528326","5721e9c849df4f0e00528327","5721e9c849df4f0e00528328","5721e9c849df4f0e00528329","5a6f6fc5043d990023daeb09"],"_id":"5721e9c849df4f0e0052831f","releaseDate":"2016-04-28T10:45:28.369Z","hasReference":true,"project":"5656d449a795770d00a2aec1","createdAt":"2016-04-28T10:45:28.369Z","hasDoc":true,"__v":2},"githubsync":"","project":"5656d449a795770d00a2aec1","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"SAFE Launcher API","slug":"safe-launcher-api-1","order":3,"from_sync":false,"reference":false,"_id":"5721e9c849df4f0e00528328","project":"5656d449a795770d00a2aec1","createdAt":"2016-03-07T18:25:17.849Z","__v":0,"version":"5721e9c849df4f0e0052831f"}}

post/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.

Definition

{{ api_url }}{{ page_api_url }}

Documentation

### Request Header ``` Content-Type: application/json ``` ### Request Payload ``` { app: { name: String, id: String, version: String, vendor: String }, permissions: Array[String] } ``` [block:parameters] { "data": { "0-0": "app.name", "h-0": "Field", "h-1": "Description", "0-1": "Name of the application requesting authorisation with the SAFE Launcher.", "1-0": "app.id", "1-1": "Unique ID for the application.\n\nThe ID should be unique among the applications provided by the vendor.\n\nIf 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.", "2-0": "app.version", "2-1": "Version of the application (to be passed as a string).", "3-0": "app.vendor", "3-1": "Vendor name of the application.", "4-0": "permissions", "4-1": "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.\n\nPermitted permission keys:\nSAFE_DRIVE_ACCESS.", "h-2": "" }, "cols": 2, "rows": 5 } [/block] ### Response [block:code] { "codes": [ { "name": 200, "code": "{\n token: String,\n permissions: Array[String]\n}", "language": "json", "status": 200 }, { "code": "Unauthorized", "language": "http", "name": "401" }, { "code": "Fields are missing", "language": "http", "name": "400" } ], "sidebar": true } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "token", "0-1": "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.", "1-0": "permissions", "1-1": "List of permissions approved by the user." }, "cols": 2, "rows": 2 } [/block] [block:api-header] { "type": "basic" } [/block] ## Examples [block:code] { "codes": [ { "code": "var request = require('request');\n\nvar endPoint = 'http://localhost:8100/auth';\n\n// authorisation payload\nvar payload = {\n \"app\": {\n \"name\":\"Sample Application\",\n \"id\":\"com.maidsafe.sample\",\n \"version\":\"0.0.1\",\n \"vendor\":\"MaidSafe\"\n },\n \"permissions\": [\n \"SAFE_DRIVE_ACCESS\"\n ]\n};\n\nvar onResponse = function(err, response, body) {\n if (err) {\n return console.error(err.message);\n }\n if (response.statusCode === 401) {\n return console.error('Failed to authorise');\n }\n console.log('Auth token', body.token);\n};\n\nrequest.post(endPoint, { \n json: true,\n body: payload\n}, onResponse);\n", "language": "javascript", "name": "Nodejs" } ], "sidebar": true } [/block]