{"_id":"54349c905b10711400c6c53b","user":"54343147fa5527080064f43f","__v":33,"parentDoc":null,"category":{"_id":"54343531bfaa3d0800c4d4b0","pages":["54349c225b10711400c6c539","54349c905b10711400c6c53b","54370bea4e799808006da391","54370fa726469424002a6e19","5480aad4e952bb1a006b320c","5638d6c12fc5520d001a4cc9","568fe01b21fcf0190071d8fb"],"project":"54343170fa5527080064f449","version":"54343531bfaa3d0800c4d4af","__v":8,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-07T18:31:12.137Z","from_sync":false,"order":0,"slug":"documentation","title":"Documentation"},"is_link":false,"version":{"_id":"54343531bfaa3d0800c4d4af","project":"54343170fa5527080064f449","__v":28,"forked_from":"54343170fa5527080064f44c","createdAt":"2014-10-07T18:47:13.086Z","releaseDate":"2014-10-07T18:47:13.086Z","categories":["54343531bfaa3d0800c4d4b0","543435b1edce040800409240","543435b9edce040800409241","543435bcedce040800409243","543435bfedce040800409244","543435c2edce040800409245","54370cc426469424002a6dfa","54370cf026469424002a6dfd","5437129d26469424002a6e2f","543712d226469424002a6e30","5480c8fd74904f1a00053c86","54aafc6eefb39016009e4d71","54ac1d36de18cc1400226e01","54ad59369219922100751732","54b41bcf4f25cb1600518d2c","54b533a3a806f40c0050d53c","54b54bbf96fe3c0b00d38d2a","54b688a27379a90c00f53a8a","54b699efbc1a46160005edfa","54b8191691011f0b00068804","54bfb002d03bfc0d0000e814","54bfb33ed03bfc0d0000e816","55a3e94e912a6e2300882cdb","55a56c370f354f0d00fd02a8","55e85ad034516037002e9325","5638ecb62fc5520d001a4cf9","572cba2fc310640e008f63d5","596e6e42c5b53b00509791b1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3.0"},"project":"54343170fa5527080064f449","updates":["54b580aa96fe3c0b00d38d97"],"next":{"pages":[],"description":""},"createdAt":"2014-10-08T02:08:16.638Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"try":true,"basic_auth":false,"results":{"codes":[]},"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":1,"body":"The MediaSilo API supports two types of authentication: [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side) and Session Auth. For both authentication methods you must send a _MediaSiloHostContext_ header whose value is your MediaSilo domain name.\n\n**Basic Authentication:**\nThis implementation is the simplest technique for enforcing access controls to web resources because it doesn't require cookies, a session identifier and login pages. Rather, HTTP Basic authentication uses static, standard HTTP headers which means that no handshakes have to be done in anticipation.\n\nCredentials are [Base64]([http://google.com](http://en.wikipedia.org/wiki/Base64) encoded and sent via https to the MediaSilo API.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Example Headers\\n\\nAuthorization : Basic a3FpcTJhZGDsOkKvbGxlZ2Ux\\nMediaSiloHostContext : myaccount\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"// Authentication failed\",\n      \"language\": \"text\",\n      \"name\": \"403\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// PHP example for authenticating requests and sending host context\\n\\n$apiurl = \\\"https://api.mediasilo.com/v3/me/\\\";\\n\\n$ch = curl_init();\\ncurl_setopt($ch, CURLOPT_URL,$apiurl);\\ncurl_setopt($ch, CURLOPT_TIMEOUT, 30);\\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER,1);\\ncurl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); \\ncurl_setopt($ch, CURLOPT_USERPWD, $username . \\\":\\\" . $password);\\ncurl_setopt($ch, CURLOPT_HTTPHEADER, Array(\\\"MediaSiloHostContext: \\\" . $hostname));\\n$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); \\n$result=curl_exec($ch);\\ncurl_close ($ch);\",\n      \"language\": \"php\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n \n**Session Authentication:**\nSessions are another method to authorize requests against the MediaSilo API.  They allow you to make requests without passing your username and password with every request, however, you have to create a session first before you can make any other requests against the API. \n\nThe session will automatically expire after 60 minutes of inactivity. Each time an API endpoint is called with the session, the expiration will be reset.\n\n1. [Create a Session](/docs/create-session) with the user's account, username, and password\n2. Include required headers on all future calls\n    * `MediaSiloSessionKey` is the `id` returned by [create-session](/docs/create-session)\n    * `MediaSiloHostContext` is the MediaSilo account input by the user\n3. [Call Ping-Pong](/docs/ping-pong) to keep the session alive when the user is idle\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/**\\n*\\n*  Create Session\\n*\\n**/\\nfunction createSession(userName, password, accountName) {\\n  $.ajax({\\n    type: \\\"POST\\\",\\n    url: \\\"https://api.mediasilo.com/v3/session\\\",\\n    data: JSON.stringify({\\n      \\\"accountName\\\": accountName,\\n      \\\"userName\\\": userName,\\n      \\\"password\\\": password,\\n      \\\"setCookies\\\": false,\\n    }),\\n    dataType: \\\"json\\\",\\n    success: function( response ) {\\n      config.sessionkey = response.id;\\n      config.hostname = accountName;\\n      config.username = username;\\n      // handle success\\n    },\\n    error: function( response ) {\\n      switch (response.status) {\\n        case 400: // Malformed request\\n          // handle 400\\n          break;\\n        case 401: // Password does not match username\\n          // handle 401\\n          break;\\n        case 404: // Username does not exist\\n          // handle 404\\n          break;\\n      }\\n    }\\n  });\\n}\\n\\n/**\\n*\\n* Get User Account Information\\n*\\n**/\\nfunction getMe() {\\n  $.ajax({\\n    type: \\\"GET\\\",\\n    dataType: \\\"json\\\",\\n    url: \\\"https://api.mediasilo.com/v3/me\\\",\\n    beforeSend: function(xhr) {\\n      xhr.setRequestHeader(\\\"MediaSiloSessionKey\\\", config.sessionkey);\\n      xhr.setRequestHeader(\\\"MediaSiloHostContext\\\", config.hostname);\\n    },\\n    success: function( response ) {\\n      config.user = response;\\n      config.firstName = response.firstName;\\n      config.lastName = response.lastName;\\n      config.email = response.email;\\n      // handle success\\n    },\\n    error: function( response ) {\\n\\t\\t\\t// handle errors\\n    }\\n  });\\n}\\n\\n\\n/**\\n*\\n*  Refresh Session\\n*  Called periodically to ensure the session is still valid\\n*\\n**/\\nfunction keepAlive() {\\n  $.ajax({\\n    type: \\\"GET\\\",\\n    dataType: \\\"text\\\",\\n    url: \\\"https://api.mediasilo.com/v3/ping\\\",\\n    beforeSend: function(xhr) {\\n      xhr.setRequestHeader(\\\"MediaSiloSessionKey\\\", config.sessionkey);\\n      xhr.setRequestHeader(\\\"MediaSiloHostContext\\\", config.hostname);\\n    },\\n    error: function( response ) {\\n      // handle errors\\n    }\\n  });\\n}\\n\\n\\n/**\\n*\\n*  Delete Session\\n*\\n**/\\nfunction deleteSession(id) {\\n  $.ajax({\\n    type: \\\"DELETE\\\",\\n    url: \\\"https://api.mediasilo.com/v3/session/\\\" + id,\\n    beforeSend: function(xhr) {\\n      xhr.setRequestHeader(\\\"MediaSiloSessionKey\\\", config.sessionkey);\\n      xhr.setRequestHeader(\\\"MediaSiloHostContext\\\", config.hostname);\\n    },\\n    error: function( response ) {\\n      // handle errors\\n    }\\n  });\\n}\",\n      \"language\": \"javascript\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Example Headers\\n\\nMediaSiloSessionKey : a123f7f995642sdf873rfd50f27bd92ea918\\nMediaSiloHostContext : myaccount\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Add your credentials to the request header rather than the URL to avoid sending your credentials clear text. Also, be sure to submit all requests over HTTPS rather than HTTP.\",\n  \"title\": \"Security Consideration\"\n}\n[/block]","excerpt":"Describes how to send credentials with your requests","slug":"authentication","type":"basic","title":"Authentication"}

Authentication

Describes how to send credentials with your requests

The MediaSilo API supports two types of authentication: [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side) and Session Auth. For both authentication methods you must send a _MediaSiloHostContext_ header whose value is your MediaSilo domain name. **Basic Authentication:** This implementation is the simplest technique for enforcing access controls to web resources because it doesn't require cookies, a session identifier and login pages. Rather, HTTP Basic authentication uses static, standard HTTP headers which means that no handshakes have to be done in anticipation. Credentials are [Base64]([http://google.com](http://en.wikipedia.org/wiki/Base64) encoded and sent via https to the MediaSilo API. [block:code] { "codes": [ { "code": "// Example Headers\n\nAuthorization : Basic a3FpcTJhZGDsOkKvbGxlZ2Ux\nMediaSiloHostContext : myaccount", "language": "http" }, { "code": "// Authentication failed", "language": "text", "name": "403" } ], "sidebar": true } [/block] [block:code] { "codes": [ { "code": "// PHP example for authenticating requests and sending host context\n\n$apiurl = \"https://api.mediasilo.com/v3/me/\";\n\n$ch = curl_init();\ncurl_setopt($ch, CURLOPT_URL,$apiurl);\ncurl_setopt($ch, CURLOPT_TIMEOUT, 30);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER,1);\ncurl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); \ncurl_setopt($ch, CURLOPT_USERPWD, $username . \":\" . $password);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, Array(\"MediaSiloHostContext: \" . $hostname));\n$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); \n$result=curl_exec($ch);\ncurl_close ($ch);", "language": "php", "name": null } ] } [/block] **Session Authentication:** Sessions are another method to authorize requests against the MediaSilo API. They allow you to make requests without passing your username and password with every request, however, you have to create a session first before you can make any other requests against the API. The session will automatically expire after 60 minutes of inactivity. Each time an API endpoint is called with the session, the expiration will be reset. 1. [Create a Session](/docs/create-session) with the user's account, username, and password 2. Include required headers on all future calls * `MediaSiloSessionKey` is the `id` returned by [create-session](/docs/create-session) * `MediaSiloHostContext` is the MediaSilo account input by the user 3. [Call Ping-Pong](/docs/ping-pong) to keep the session alive when the user is idle [block:code] { "codes": [ { "code": "/**\n*\n* Create Session\n*\n**/\nfunction createSession(userName, password, accountName) {\n $.ajax({\n type: \"POST\",\n url: \"https://api.mediasilo.com/v3/session\",\n data: JSON.stringify({\n \"accountName\": accountName,\n \"userName\": userName,\n \"password\": password,\n \"setCookies\": false,\n }),\n dataType: \"json\",\n success: function( response ) {\n config.sessionkey = response.id;\n config.hostname = accountName;\n config.username = username;\n // handle success\n },\n error: function( response ) {\n switch (response.status) {\n case 400: // Malformed request\n // handle 400\n break;\n case 401: // Password does not match username\n // handle 401\n break;\n case 404: // Username does not exist\n // handle 404\n break;\n }\n }\n });\n}\n\n/**\n*\n* Get User Account Information\n*\n**/\nfunction getMe() {\n $.ajax({\n type: \"GET\",\n dataType: \"json\",\n url: \"https://api.mediasilo.com/v3/me\",\n beforeSend: function(xhr) {\n xhr.setRequestHeader(\"MediaSiloSessionKey\", config.sessionkey);\n xhr.setRequestHeader(\"MediaSiloHostContext\", config.hostname);\n },\n success: function( response ) {\n config.user = response;\n config.firstName = response.firstName;\n config.lastName = response.lastName;\n config.email = response.email;\n // handle success\n },\n error: function( response ) {\n\t\t\t// handle errors\n }\n });\n}\n\n\n/**\n*\n* Refresh Session\n* Called periodically to ensure the session is still valid\n*\n**/\nfunction keepAlive() {\n $.ajax({\n type: \"GET\",\n dataType: \"text\",\n url: \"https://api.mediasilo.com/v3/ping\",\n beforeSend: function(xhr) {\n xhr.setRequestHeader(\"MediaSiloSessionKey\", config.sessionkey);\n xhr.setRequestHeader(\"MediaSiloHostContext\", config.hostname);\n },\n error: function( response ) {\n // handle errors\n }\n });\n}\n\n\n/**\n*\n* Delete Session\n*\n**/\nfunction deleteSession(id) {\n $.ajax({\n type: \"DELETE\",\n url: \"https://api.mediasilo.com/v3/session/\" + id,\n beforeSend: function(xhr) {\n xhr.setRequestHeader(\"MediaSiloSessionKey\", config.sessionkey);\n xhr.setRequestHeader(\"MediaSiloHostContext\", config.hostname);\n },\n error: function( response ) {\n // handle errors\n }\n });\n}", "language": "javascript", "name": null } ] } [/block] [block:code] { "codes": [ { "code": "// Example Headers\n\nMediaSiloSessionKey : a123f7f995642sdf873rfd50f27bd92ea918\nMediaSiloHostContext : myaccount", "language": "http" } ] } [/block] [block:callout] { "type": "info", "body": "Add your credentials to the request header rather than the URL to avoid sending your credentials clear text. Also, be sure to submit all requests over HTTPS rather than HTTP.", "title": "Security Consideration" } [/block]