Campaign API keys

The Campaign API (v0) authenticates every request with a brand key. A brand key belongs to the brand, not to a person, and reads only that brand.

Create a keyCopy Anchor Link

Full admins of the brand create and revoke keys. Limited admins can see the list but not change it. See Full vs limited admins.

New keys need the brand to be on the Scale plan. See Plans and features.

1. Open your brand and go to SettingsIntegrationsAPI Keys.
2. Click Create key and name it after where it will be used.
3. Pick when it Expires after, and tick its Permissions. For the Campaign API, tick both The brand's analytics and exports and Payout settings, cycles and payouts: Campaign API responses include spend, so a key needs both.
4. Click Create key and copy the key right away. For security, Bloss stores only a hash of it and can't show it again. If you lose it, create a new key and revoke the old one.

Keys look like blsk_ followed by 43 random characters. The keys list shows each key's name and first few characters so you can tell them apart. The same key also reads the Brand API, within its permissions. See Brand keys for everything about permissions and expiry.

Keys from before permissionsCopy Anchor Link

Keys created before permissions existed are marked Campaign API (v0) only. They keep working on the Campaign API, on any plan, and you can still revoke them. They don't work on the Brand API.

Send the keyCopy Anchor Link

Use either header. They're equivalent:

curl https://www.bloss.app/api/v0/cycles \
  -H "Authorization: Bearer blsk_your_key"

ScopeCopy Anchor Link

• A key belongs to one brand. The brand isn't part of the URL: Bloss works it out from the key, so a key can never read another brand's data.
• Ids from another brand (a cycle, tag or group id) behave as if they don't exist and return 400.
• Keys are read-only.

Revoke a keyCopy Anchor Link

In the same API Keys list, click the revoke button next to the key and confirm with Revoke key. Revoking takes effect immediately: requests with that key get 401 Invalid or revoked API key. Revoked keys stay in the list, marked as revoked, for your records.

A key with an expiry date stops working the same way once it expires, and shows Expired.