Authentication & Scopes

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

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

Where To Store Tokens

Use one canonical local secret: VAYBEL_PAT.

For Claude Code, prefer storing the token in Claude Code settings so it is available to both the Vaybel MCP server and the official Vaybel Skills plugin:

{
  "env": {
    "VAYBEL_PAT": "vbl_pat_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Then reference it from MCP config instead of pasting the token into the config file:

{
  "mcpServers": {
    "vaybel": {
      "type": "http",
      "url": "https://mcp.vaybel.com/",
      "headers": {
        "Authorization": "Bearer ${VAYBEL_PAT}"
      }
    }
  }
}

Scopes

Every tool declares the scope(s) it requires. A PAT missing the scope gets missing scope as a clean tool error. The dashboard token creator selects all public scopes by default — uncheck only what you want to deny.

Read scopes

Write scopes

Rate Limits

Rate limits apply per-PAT, per-tool, on a fixed 60-second window. Hitting one raises a clean rate limit exceeded error with retry_after_seconds.

Credit balance provides the finer gating for billable tools — you'll hit insufficient credits before a rate limit on a real workload.

Credit Charging

Most tools are free. A handful charge from the same credit balance your dashboard uses — no separate developer meter.

Three pre-flight gates prevent surprises:

1. Out-of-credit calls fail fast — the tool body runs a balance check before dispatching any Celery work.
2. Idempotent tools (generate_design, generate_mockup, create_listing, publish_listing, optimize_product, content.generate, generate_launch_concept) dedupe on retry, so a flaky-network loop doesn't double-bill.
3. trend.generate_launch_concept short-circuits to free when the concept is already cached.

Read tools and status polls are always free.

Errors You Might See