Keys and scopes
A Buzzmark API key, made in Settings under Developers, has one scope: Read, Draft (reads too) or Schedule (reads and drafts too).
It acts as the person who made it, with their role and brands, and never more: a contributor's key can't schedule.
One key works with the REST API, the CLI and AI apps without sign-in. Each plan holds a number of live keys per organization.
What a key can do
| Scope | What it allows |
|---|---|
| Read | Every request that only reads: your sets, accounts, brand profiles, best times, posts and their numbers. The dry run too: it saves nothing. |
| Draft | Everything Read allows, plus saving, changing and deleting drafts, adding pictures and videos, and Buzz's writing tools. |
| Schedule | Everything Draft allows, plus scheduling a post and moving, taking back or retrying it. |
Endpoints gives each endpoint's scope. A request beyond the key's scope answers 403 forbidden, and nothing runs.
A key acts as its maker
A key uses its maker's role and brands as they are now: a teammate with chosen brands reaches only those, and a change applies to their keys at once.
Scheduling through the API is for an owner or an editor. A contributor's key can read and draft, and a request to schedule, move, take back or retry a post answers 403, even with the Schedule scope. When someone leaves your organization or their seat is locked, their keys stop working.
Send the key
Send the key on every request as Authorization: Bearer followed by the key, which starts with bzk_. A key in the address is refused. Keep it in your code's secret store or the workflow tool's credentials, never in the code itself.
GET /me answers what the key can do (can.read, can.draft, can.schedule), its scopes, when it expires and its limit, so a workflow can check itself before it starts.
How many keys
| Plan | Live keys |
|---|---|
| Growth | 3 |
| Reach | 5 |
| Scale | 10 |
| Agency | 25 |
The count is per organization, and an expired or revoked key doesn't count. A plan with fewer keys than you have keeps the ones that work. Make one key per app or workflow, so revoking one stops only that one.
Expire or revoke a key
Expires sets when a key stops working; the default is Never. To stop a key now, press Revoke next to it in Settings, under Developers, then Revoke it. It stops within a minute.
Buzzmark keeps only a fingerprint of a key and its last 4 characters, so it can't show the key again. If you lose one, revoke it and make another. Sign-in, keys and limits has the steps.
Where to next
- Check and schedule posts
POST /posts/validate checks a post against each account's platform rules and saves nothing; POST /posts and POST /posts/bulk run the same check, then schedule.
- Errors and limits
A Buzzmark API refusal is JSON with a code, a message, whether a retry may work, and a request id, and its HTTP status matches the code.
- Sign-in, keys and limits
An AI app signs in on a Buzzmark page in your browser, where you press Allow, and works as you until you disconnect it.
- Invite your team
On Reach, Scale and Agency the owner invites teammates from Settings, Organization, as an Editor or a Contributor.