"docs.beeswax.com" has a new address: "api-docs.freewheel.tv/beeswax." Please update your bookmarks accordingly.

Buzz Key

An instance of Buzz supports multiple Accounts with segregated data. However, there are scenarios where multiple instances of Buzz must interact, and the uniqueness of an auto-generated key, such as account_id, cannot be assured. To solve this problem, each instance of Buzz includes a "Buzz Key", set by the system administrator.

For most objects in the API, the Buzz Key has no effect. However, for objects that have the potential to be consumed by a shared system, the Buzz Key is used to enforce object uniqueness. For example, in the Segment object, there is both a segment_id field and a segment_key field. The latter is used for targeting segments, sharing segments, and otherwise working with the object. The reason is because segments are often shared between Accounts, and it is possible to imagine a scenario where multiple Buzz instances will need to share segments.

Buzz Key vs account_id

When you execute a GET query that includes an account_id field, the field will show as a compound key such as stinger-2 where the Buzz Key is 'stinger' and the numeric account_id from the database is 2. Unless you are a Super User (administrator) you can safely ignore the account_id field since you cannot POST or PUT objects in other accounts and any GET queries will automatically be restricted to the account_id to which you belong.

Conventions

Some considerations about the Buzz Key:

  • Buzz Keys must be unique within the overall Beeswax cloud
  • The value can never be changed once set
  • The value must only use alphanumeric characters

Usage

Where Buzz Key is used:

  • The Buzz Authentication cookie is named <buzz_key>_<cookie_name>
  • Any GET request that includes account_id in the response will be formatted as <buzz_key>-<account_id>
  • Segments are uniquely identified by the segment_key field, which is formatted as <buzz_key>/<segment_id>
  • Creative Assets are uploaded to a directory with the path /<buzz_key>/<account_id>/<advertiser_id>
  • Segment Upload / Segment Update are uploaded to a directory with the path /<buzz_key>/<account_id>
  • The {{BUZZ_KEY}} macro can be used in creatives.