Authentication

🚧

Upgrade Notice

The 2.0 API authentication is available and may be used to authenticate to either 0.5 or 2.0 resources. Read more: Authentication.

Assuming you have an active User account on the Buzz system, you authenticate by sending a POST request with your credentials to the Authentication 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.

CURL Authentication Example

In the CURL example to the right, 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.

curl -X POST "[path]/rest/authenticate" -c cookies.txt -d '{"email":"[email protected]", "password":"123456"}'

{
    "success": "true",
    "message": "Cookie set successfully"
}

Creating a Longer-Lasting Session

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:

curl -X POST "[path]/rest/authenticate" 
	-c cookies.txt -d '{"email":"[email protected]", "password":"123456","keep_logged_in":true}'

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.

Using Basic Authentication

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.

curl -X POST "[path]/rest/advertiser" 
	--user [email protected]:password 
  -d '{"advertiser_name":"new advertiser"}'

For more details on authentication, passwords, etc, see: Users, Passwords, and the API.

Rate Limiting

Please note, the authenticate API endpoint is rate limited for security reasons. If you exceed the rate limit the API will respond with a 429 error.