API Authentication

The Vizzybl public API is authenticated with workspace-scoped API keys. Every key belongs to exactly one workspace — the workspace is derived from the key, so you never pass a tenant or brand ID.

API access is available on Ultra and Enterprise plans.

Create an API key

1. Open Settings → API Keys. You need the owner or admin role in the workspace.
2. Click Create API key, give it a descriptive name, and choose its scopes.
3. Optionally set an expiry — between 1 and 365 days.
4. Copy the key immediately. It starts with vzbl_live_ and is shown only once. Vizzybl stores only a SHA-256 hash of the key, so it can never be retrieved again — store it like a password.

Each workspace can hold up to 25 active keys. Revoke keys you no longer use to stay under the limit.

Authenticate requests

Send the key as a Bearer token on every request:

curl -s -H "Authorization: Bearer vzbl_live_..." \
  https://vizzybl.ai/api/v1/brand/me

If your tooling can't set an Authorization header, the x-api-key header is accepted as an alternative:

curl -s -H "x-api-key: vzbl_live_..." \
  https://vizzybl.ai/api/v1/brand/me

Scopes

Scopes control which endpoints a key can call. Grant the minimum a key needs.

Scope	Grants access to
read:brand	Brand identity & engines
read:visibility	Visibility / share of voice
read:prompts	Monitored prompts
read:responses	AI answers (verbatim)
read:citations	Citations
read:*	All read access
write:audits	Run GEO audits (writes, metered)
write:prompts	Create & scrape prompts (writes, metered)

Two rules to remember:

• read:* covers reads only. The wildcard grants every read: scope, but never a write scope.
• Write scopes are exact-match and metered. A key can only call a write endpoint if it holds that exact scope, and write actions consume credits from your workspace balance.

Expiry and revocation

• Expiry is optional. If set, it must be between 1 and 365 days; the key stops working the moment it expires.
• Revoke a key at any time from Settings → API Keys. Revocation takes effect immediately.
• Keys stop working automatically if your plan drops below Ultra.

Security best practices

• Treat keys like passwords — anyone with a key can read your workspace's GEO data, and keys with write scopes can spend credits.
• Create one key per integration and name it after what uses it, so you can revoke a single integration without breaking the others.
• Prefer granular read scopes over read:* when an integration only needs one data family.
• Set an expiry on keys used for one-off or short-lived work.
• Never commit a key to source control or paste it into shared documents. If a key may have leaked, revoke it and create a new one.

Next steps

• API Endpoints — every endpoint, with scopes, rate limits, and error codes
• MCP Server — use your Vizzybl data from Claude, Cursor, or VS Code without writing API calls
• Claude Skill — teach Claude to query the API directly