Authentication

Every request sends a workspace token as a Bearer token. Create tokens in the dashboard, give each one only the abilities it needs, and revoke any you no longer use.

Who can manage tokens#

Owners, admins and developers can create and revoke tokens. Marketers can't open the page.

Tokens belong to the workspace, not to the person who created them, so they keep working if that person leaves the team. The Sandbox and Production each have their own tokens: a Sandbox token only works on the Sandbox address, and a Production token only on the Production one. See Sandbox and Production.

Create a token#

1. 1
   Open Platform API

   In the dashboard, switch to the workspace the token is for, then open Configuration › Platform API. The page lists the workspace's tokens and shows whether you're in the Sandbox or Production.
2. 2
   Create the token

   Click Create token. Give it a Name that says what it's for, such as "Zapier" (up to 80 characters), tick at least one ability, and optionally choose an Expires date. If you haven't confirmed it's you recently, Bubbl asks you to first.
3. 3
   Copy it now

   The token is shown once. Copy it and store it somewhere safe, such as your password manager or your server's secrets store. Bubbl keeps only a hash of it, so it can't show it to you again. If you lose it, create a new token and revoke the old one.

Every token starts with bubbl_, so secret scanners (such as GitHub's) can recognise one that's been leaked.

Send the token#

Send the token in the Authorization header of every request, over HTTPS:

curl https://api.bubbl.tech/platform/v1/campaigns \
  -H "Authorization: Bearer $BUBBL_API_TOKEN"

const response = await fetch('https://api.bubbl.tech/platform/v1/campaigns', {
  headers: { Authorization: `Bearer ${process.env.BUBBL_API_TOKEN}` },
});

import os
import requests

response = requests.get(
    "https://api.bubbl.tech/platform/v1/campaigns",
    headers={"Authorization": f"Bearer {os.environ['BUBBL_API_TOKEN']}"},
    timeout=30,
)

Abilities#

Abilities decide what a token can do. You choose them when you create the token, and they can't be changed afterwards: to change them, create a new token and revoke the old one.

A write ability doesn't include the matching read one, so tick both if the token needs to read as well as change things. GET /me needs no ability.

A request the token doesn't have the ability for gets 403 with the code missing_ability:

{
  "error": {
    "code": "missing_ability",
    "message": "This token doesn't have the campaigns:write scope."
  }
}

Expiry#

A token with no expiry date works until it's revoked. If you choose an Expires date, the token stops working at 00:00 UTC on that date. After that, requests get 401 with the code token_expired. The token stays in the list, marked Expired, until you revoke it.

Last used#

The list shows when each token was last used and from which IP address. It's updated at most every five minutes, so a token in constant use shows a time up to five minutes old. A token that has never been used shows Never used.

Revoke a token#

Click Revoke next to the token and confirm. Anything still using the token stops working immediately, and this can't be undone. Like creating a token, revoking one may ask you to confirm it's you first.

Keep tokens safe#

• Keep tokens on your servers or in your automation tool's settings. Never put one in a mobile app, a web page or a public repository.
• Create one token per integration, with only the abilities it needs, and name it after the integration. Then you can revoke one without breaking the others.
• If a token might have leaked, revoke it straight away and create a new one.

Authentication errors#

See Errors for every error code.