{"_id":"56cf45b944c5700b0095c175","__v":5,"parentDoc":null,"user":"56c39c05bc41330d009f25d7","category":{"_id":"56c35c57c0c4630d004e8650","version":"56c35c56c0c4630d004e864f","__v":17,"pages":["56c35c58c0c4630d004e8652","56c38f9c2d97560d00e23cb8","56c39b11e1e4190d003429b0","56c3a90c28bd680d005e7aa3","56c7b98a8bf67e0d0073477a","56c7b9d7379b311700ed8fe1","56c7bcc55652c217008e0923","56c7bee8606ee717003c4769","56cf423f8629f91300fd9779","56cf45b944c5700b0095c175","56cf4709287eb20b009f9eec","56cf49208acacb1300814884","56cf4c4c287eb20b009f9f01","56cf4d968629f91300fd9797","56cf4ede8acacb1300814890","56cf520b8629f91300fd97a9","56cf52d5287eb20b009f9f12"],"project":"56c35c56c0c4630d004e864c","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-02-16T17:28:55.483Z","from_sync":false,"order":0,"slug":"documentation","title":"Buzz API Overview"},"version":{"_id":"56c35c56c0c4630d004e864f","project":"56c35c56c0c4630d004e864c","__v":8,"createdAt":"2016-02-16T17:28:54.864Z","releaseDate":"2016-02-16T17:28:54.864Z","categories":["56c35c57c0c4630d004e8650","56c7b9e5379b311700ed8fe3","56c7bab4606ee717003c4766","56c7bb3613e5400d001e8cbd","56cf3f5a5267d70b00494c4b","56cf3f866c5d7a13005ee894","56fd3956caad892200847bce","599da256e7742b002588bb02"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.5.0","version":"0.5"},"project":"56c35c56c0c4630d004e864c","updates":["593ee2c8f69a3b00314a93e4"],"next":{"pages":[],"description":""},"createdAt":"2016-02-25T18:19:37.264Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":1,"body":"Assuming you have an active [User](doc:users) account on the Buzz system, you authenticate by sending a POST request with your credentials to the `authenticate` method and storing the resulting cookie in a local variable in your client. The Buzz cookie's name varies between Buzz instances, but is always in the pattern `<buzz_key>_buzz_cookie`. The expiration of the credentials is an environment setting, but by default is set at 15 minutes.\n\nTo enable a more persistent login, add `\"keep_logged_in\":true` to the POST.  \n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"CURL Authentication Example\"\n}\n[/block]\nIn the CURL example below, the cookie is stored in the cookies.txt file by using the -c parameter. The following command will attempt to authenticate the user with the email provided. Note the `-c` parameter is only used for authenticate, all other commands should use `-b`. [path] should be buzzkey.api.beeswax.com.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[path]/rest/authenticate\\\" -c cookies.txt -d '{\\\"email\\\":\\\"foo:::at:::bar.com\\\", \\\"password\\\":\\\"123456\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nIf these credentials are valid, the request should return the message:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": \\\"true\\\",\\n    \\\"payload\\\": \\\"Cookie set successfully\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"Creating a Longer-Lasting Session\"\n}\n[/block]\nTo execute a \"Keep me logged in\" functionality or to maintain a significantly longer session, set the `keep_logged_in` parameter to true in the POST to `authenticate`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[path]/rest/authenticate\\\" -c cookies.txt -d '{\\\"email\\\":\\\"foo@bar.com\\\", \\\"password\\\":\\\"123456\\\",\\\"keep_logged_in\\\":true}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nWhen authenticated with `keep_logged_in` a second cookie is set with a 30-day expiration and subsequent API requests will create new sessions. When using these longer-lasting sessions make sure your cookie is both read- and write-able on every request since the value may change as new sessions are created. In cURL this is accomplished by passing both the `-b cookies.txt` and `-c cookies.txt` parameters on every request.\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"Using Basic Authentication\"\n}\n[/block]\nBy default Buzz does not support Basic Authentication, but it can be enabled on custom installations. When authenticating using this method, pass the user's email address and password in the request header of every request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[path]/rest/advertiser\\\" --user your@email.com:password -d '{\\\"advertiser_name\\\":\\\"new advertiser\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nFor more details on authentication, passwords, etc, see: [Users, Passwords, and the API](doc:users-passwords-and-the-api).","excerpt":"","slug":"authentication","type":"basic","title":"Authentication"}
Assuming you have an active [User](doc:users) account on the Buzz system, you authenticate by sending a POST request with your credentials to the `authenticate` method and storing the resulting cookie in a local variable in your client. The Buzz cookie's name varies between Buzz instances, but is always in the pattern `<buzz_key>_buzz_cookie`. The expiration of the credentials is an environment setting, but by default is set at 15 minutes. To enable a more persistent login, add `"keep_logged_in":true` to the POST. [block:api-header] { "type": "post", "title": "CURL Authentication Example" } [/block] In the CURL example below, the cookie is stored in the cookies.txt file by using the -c parameter. The following command will attempt to authenticate the user with the email provided. Note the `-c` parameter is only used for authenticate, all other commands should use `-b`. [path] should be buzzkey.api.beeswax.com. [block:code] { "codes": [ { "code": "curl -X POST \"[path]/rest/authenticate\" -c cookies.txt -d '{\"email\":\"foo@bar.com\", \"password\":\"123456\"}'", "language": "curl" } ] } [/block] If these credentials are valid, the request should return the message: [block:code] { "codes": [ { "code": "{\n \"success\": \"true\",\n \"payload\": \"Cookie set successfully\"\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "post", "title": "Creating a Longer-Lasting Session" } [/block] To execute a "Keep me logged in" functionality or to maintain a significantly longer session, set the `keep_logged_in` parameter to true in the POST to `authenticate`: [block:code] { "codes": [ { "code": "curl -X POST \"[path]/rest/authenticate\" -c cookies.txt -d '{\"email\":\"foo@bar.com\", \"password\":\"123456\",\"keep_logged_in\":true}'", "language": "curl" } ] } [/block] When authenticated with `keep_logged_in` a second cookie is set with a 30-day expiration and subsequent API requests will create new sessions. When using these longer-lasting sessions make sure your cookie is both read- and write-able on every request since the value may change as new sessions are created. In cURL this is accomplished by passing both the `-b cookies.txt` and `-c cookies.txt` parameters on every request. [block:api-header] { "type": "post", "title": "Using Basic Authentication" } [/block] By default Buzz does not support Basic Authentication, but it can be enabled on custom installations. When authenticating using this method, pass the user's email address and password in the request header of every request. [block:code] { "codes": [ { "code": "curl -X POST \"[path]/rest/advertiser\" --user your@email.com:password -d '{\"advertiser_name\":\"new advertiser\"}'", "language": "curl" } ] } [/block] For more details on authentication, passwords, etc, see: [Users, Passwords, and the API](doc:users-passwords-and-the-api).