Authentication

📘

Compatibility with the 0.5 API

Authentication is both backwards and forwards compatible between the 0.5 and 2.0 APIs. You may authenticate with either version then use the same credentials when making requests to resources on either version.

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

To enable a more persistent login, add "keep_logged_in":true to the POST.

CURL Authentication Example

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. The [path] should always be [buzz_key].api.beeswax.com where [buzz_key] represents your unique instance of Buzz as described here: Buzz Key .

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

{
    "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/v2/authenticate" 
  -c cookies.txt 
  -d '{"email":"[email protected]", "password":"123456", "keep_logged_in":true}' 
  -H "Content-Type: application/json"

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 upon request. 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/v2/[resource]" 
  --user [email protected]:password 
  -d '{"advertiser_name":"new advertiser"}'
  -H "Content-Type: application/json"

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.

Authenticating Across Accounts ("Masquerading")

If your Buzz instance. is enabled for Multi-Account Users and the User being authenticated is enabled with the multi_account setting you may specify an account_id when authenticating. Once authenticated under this account, all subsequent API calls will work within this "masqueraded" account. For example, the request below authenticates the user into account 3:

curl -X POST "[path]/rest/v2/authenticate" 
  -c cookies.txt 
  -d '{"email":"[email protected]", "password":"123456", "account_id":3}' 
  -H "Content-Type: application/json"