API tokens
Create a personal API token for the Platform API or an AI agent, choose what it can read, and revoke it when you're done.
A personal API token lets an app, a script or an AI agent read your Bloss data through the Platform API and the MCP server. Tokens are read-only: nothing can be changed with them. Each token belongs to you and reads only what you can see in the app yourself.
Create a token
Open your account
Open your profile menu at the bottom of the sidebar and click Account. Find the API tokens card and click Create token.
Open Account SettingsSign in again if asked
Creating a token needs a sign-in from the last 10 minutes. If yours is older, you see Sign in again to create a token. Click Sign in again: Bloss signs you out, and after you sign back in you return to your account page. Click Create token again.
Fill in the form
- Name: what the token is for, so you can tell tokens apart later (for example "Claude" or "Weekly report script").
- Expires after: how long the token works (see Expiry).
- Permissions: tick only what the app or agent needs (see Permissions).
- Only these brands (optional): limit the token to some of your brands (see Limit a token to some brands).
Click Create token.
Copy the token, or connect your agent
The Token created window shows the token once. Click the copy button and store it somewhere safe, such as a password manager.
To use the token with an AI agent, pick your app under Connect an AI agent (MCP) in the same window: Claude Code, Cursor, VS Code, Claude Desktop or Other. The setup already includes your token, so you copy one command or click Add to Cursor or Add to VS Code. You don't edit the token in by hand. See AI agents (MCP).
Once you close the window there's no way to see the token again. If you lose it, revoke it and create a new one.
Tokens start with blsp_. Your list shows each token's first few characters, so you can tell which one an app is using.
You can have up to 25 active tokens at a time.
Permissions
Permissions decide which endpoints a token can call. Every box starts unticked: give each token only what it needs.
Creator & coach
| Permission | What it reads |
|---|---|
| Your creator profile, stats, brands, videos, bounties and games | Your marketplace profile, your stats, the brands you create for and their posting rules, your videos and daily views, the team's views where a brand shares them, bounties, Streak Survivor, your support tickets and your cross-posts. |
| Your earnings, payouts and payout-account status (Money data) | What you've earned, been paid and have pending in each brand, your payouts and referral payouts, and your payout setup (masked). |
| Your managed accounts, posts, orders and wallet | Managed accounts you can see, if you use them. |
| Your coaching workspace: students, notes, stages and rules | Your coaching workspace, if you're a coach. |
Account
| Permission | What it reads |
|---|---|
| Your account: name, email, roles and memberships | Who you are and every brand you belong to, with your role in each. Most apps and agents need this to find the right ids. |
Brand (Scale plan)
These permissions read brands on the Scale plan that you administer, through the Brand API. Leave them unticked for creator and coaching data. The ones marked Money data (Payout settings, cycles and payouts, Funds balance and ledger and Subscription state) work only if you're a full admin of the brand. What each permission reads is in What you can read.
Money data
Permissions marked Money data cover earnings, payouts and payout details. They're never on by default, and a token without them can't read any amount. Payout details stay masked even with them: you see where you're paid and whether your account is set up, never a full email address or account number.
Expiry
Choose 30 days, 90 days (the default), 180 days or 365 days. A token can't last longer than a year, and there are no tokens that never expire.
When a token expires it stops working and shows Expired in your list. To keep an app running, create a new token before the old one expires and swap it in.
Limit a token to some brands
Tick Only these brands and choose brands to keep a token away from the rest. Leave it off to let the token read every brand you belong to. You see this option only if you belong to at least one brand.
A limited token:
- answers
404for any other brand, as if it didn't exist; - lists only the chosen brands in
GET /meand in your earnings totals; - can't read your stats across all brands, since those add up every brand. Use the per-brand endpoints instead.
Your coaching workspace isn't tied to a brand, so this option doesn't limit it.
Your tokens
Each token in the API tokens card shows its status (Active, Expired or Revoked), the first characters of the token, when it was Created, when it Expires, when it was Last used, which Brands it can read and its Permissions.
Last used can lag by a few minutes.
Once a token has been revoked or has expired, the card shows a filter above the list: Active (the default), Revoked & expired or All, each with a count. Revoked and expired tokens are hidden until you pick one of the other two.
Revoke a token
- In the API tokens card, click Revoke next to the token.
- Click Revoke token to confirm.
Apps and agents using the token stop working right away, and this can't be undone. The token stays in your list, marked Revoked, for your records. Revoke a token as soon as you stop using it or think it may have leaked.
Brand keys
A brand key belongs to a brand, not to you. Use one for an integration that should keep working when people join or leave the brand's team. A brand key reads only its own brand, and only what its permissions allow.
New brand keys need the brand to be on the Scale plan (see Plans and features). On another plan, Create key isn't shown; the agency owner changes the brand's plan in agency billing. Keys the brand already has stay listed and can still be revoked.
Full admins of the brand create and revoke brand keys. Limited admins can see the list but not change it. See Full vs limited admins.
- Open your brand and go to SettingsIntegrationsAPI Keys.
- Click Create key and name it after where it will be used.
- Pick when the key Expires after: No expiry (the default), or 30, 90, 180 or 365 days.
- Tick the Permissions the key needs. They're the brand permissions only, and the ones marked Money data expose spend, payout or billing figures.
- Click Create key, then copy the key right away. It starts with
blsk_and can't be shown again. If you lose it, create a new key and revoke the old one. - To use the key with an AI agent, pick your app under Connect an AI agent (MCP) in the same window. The setup already includes the key, under the server name
bloss-brand, so it can sit next to your own token in the same app.
Permissions the Campaign API needs
A brand key also reads the Campaign API
when it has both The brand's analytics and exports and Payout settings,
cycles and payouts. Without both, its Campaign API requests get 401.
The keys list shows each key's status (Active, Expired or Revoked), first few characters, permissions, when it Expires and when it was Last used. A key that reaches its expiry date stops working and shows Expired. Once the brand has a revoked or expired key, the same Active, Revoked & expired and All filter appears above the list, set to Active.
Keys created before permissions existed are marked Campaign API (v0) only. They keep working on the Campaign API until that version is retired, and you can still revoke them. New keys always get permissions.
To revoke a brand key, click the revoke button next to it and confirm with Revoke key. Requests with it stop working right away.
Keep tokens secret
Treat a token like a password. Anyone who has it can read the data its permissions allow, as you.
- Don't paste tokens into chats, tickets, screenshots or shared documents.
- Keep them out of front-end code, mobile apps and public repositories. Store them in a password manager or your tool's secret settings.
- Use one token per app or agent, so you can revoke one without breaking the others.
Related
- Platform API: call the API with your token.
- AI agents (MCP): connect Claude, Cursor and other agents.
Last reviewed Oct 23, 2026