API authentication
Authenticate with a reveal-once site token and the smallest required scopes.
Send the token as a bearer credential:
Authorization: Bearer vc_...
Tokens are created in Dashboard > Connect, belong to one site, and are shown once.
Responses
- Missing or invalid credential: HTTP
401 - Valid token without the required scope: HTTP
403withFORBIDDEN - Exceeded hosted usage budget: HTTP
429withRATE_LIMIT
MCP and REST calls count against the same hosted workspace budget.
Mutations consume the write budget as well as the call budget over both transports. This includes scheduling or unscheduling a post, rotating a preview link, unarchiving a post, and updating asset metadata. Read-only tools remain available when only the write budget is exhausted.
Limits
Hosted workspaces share these budgets across all keys and calls:
| Free | Paid | |
|---|---|---|
| Calls | 30/minute, 300/day, 1,000/month | 120/minute, 5,000/day, 155,000/month |
| Writes | 50/day, 200/month | 500/day, 15,500/month |
Each key also has its own per-minute cap: 20 calls on free, 60 on paid. A workspace can have at most 10 active keys; only the owner can create or revoke them. Self-hosted installs do not enforce these budgets.
Over REST, an over-limit response is HTTP 429 with RATE_LIMIT, a retryAfterSeconds field in the error body, and Retry-After plus X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset / X-RateLimit-Metric / X-RateLimit-Period headers. Over MCP, a quota failure inside tools/call returns an error tool result with code: "RATE_LIMIT" and retryAfterSeconds — no headers; a quota failure on tools/list is an HTTP 429 JSON-RPC error. See error shapes for both MCP shapes.
Storage
Store the token in a secret manager, environment variable, or a local credential file with restricted permissions. Do not embed it in browser code or commit it to a repository.