Personal Access Tokens (PATs)
PATs are long-lived, per-organization bearer tokens. Every MCP request carries one in the Authorization header:
Authorization: Bearer vbl_pat_live_<32 urlsafe chars>
Token Format
| Component | Example | Meaning |
|---|---|---|
| Prefix | vbl_pat_live_ | Production. Registered with GitHub secret scanning. |
| Prefix | vbl_pat_test_ | Non-production environments. |
| Body | 32 URL-safe characters | 24 bytes of entropy from secrets.token_urlsafe(). |
At creation the full token is shown once. Only a SHA256 hash of the raw value is persisted — a stolen database row cannot be replayed as a token.
Lifecycle
Create
Dashboard → Settings → MCP → Create token. Choose a label and scopes. Up to ten active PATs per organization.
Rotate
Create a new token, swap your client config over, then revoke the old one. Tokens have no expiry — rotation is entirely on your schedule.
Revoke
Any row in the Settings list can be revoked. Rejection is immediate; in-flight requests that already passed auth complete normally.
Scopes
Every tool declares the scope(s) it requires. A PAT missing the scope sees 403 with a missing scope message.
| Scope | Tools It Unlocks |
|---|---|
brand_dna:read | brand_dna.get_brand_dna |
catalog:read | catalog.list_blanks |
credits:read | credits.check_credits |
design:read | design.get_design_status, design.wait_for_design |
design:write | design.generate_design |
mockup:read | mockup.get_mockup_status |
mockup:write | mockup.generate_mockup |
Principle of Least Privilege
Assign only the scopes a given integration needs. A monitoring agent that polls status doesn't need design:write — give it design:read + mockup:read and nothing more.
Rate Limits
Rate limits apply per-PAT per-tool. Exceeding a limit returns 429 with a Retry-After header.
| Tool | Limit |
|---|---|
design.generate_design | 10 / minute |
mockup.generate_mockup | 20 / minute |
| All other public tools | No explicit MCP-layer limit (platform-level limits still apply) |
Credit balance provides the finer gating for billable tools — you'll hit insufficient credits before you hit a rate limit on a real workload.
Errors You Might See
| Status | Reason | Fix |
|---|---|---|
401 | Missing or malformed Bearer token | Re-check the Authorization header; restart the client after config changes |
401 | Unknown or revoked PAT | Revoke from Settings and create a fresh one |
403 | Tool requires a scope your PAT doesn't carry | Re-create the PAT with the missing scope |
429 | Rate limit exceeded | Respect Retry-After; batch requests where possible |
| Tool error | insufficient credits: requires N, available M | Top up credits, or drop quality="standard" for mockups |