Skip to main content

Authentication & API keys

Every surface — REST, CLI, MCP — authenticates with a long-lived API key.

Creating a key​

Keys are created in the TestVibe app under Settings → CLI & API keys. A key looks like:

tvb_9hK2mPqRsT4uVwXyZ1aB3cD5eF7gH8jL0nQ6rS2tU4v
  • The tvb_ prefix plus 43 base62 characters.
  • The full key is shown exactly once, at creation. Only a hash is stored server-side; if you lose the key, revoke it and create a new one.
  • The Settings panel shows each key's display prefix (tvb_XXXXXXXX), creation date, and last-used time.

Using a key​

Send it as a bearer token on every request:

curl -H "Authorization: Bearer $TESTVIBE_API_KEY" \
  "$TESTVIBE_SERVER/api/v1/ops/projects"

The CLI and MCP server read it from testvibe login, the TESTVIBE_API_KEY environment variable, or the saved machine config — see The testvibe CLI.

What a key can do​

A key acts as the user who created it, inside the workspace it was created in:

  • It can see and operate on every project of that workspace (subject to the creator's access).
  • It stops working immediately if it is revoked, if it reaches its optional expiry, or if the creating user leaves the workspace.

Failure mode​

Requests without a valid key get 401:

{
  "error": "unauthorized",
  "message": "A valid API key is required (Authorization: Bearer tvb_…)."
}
warning

Key hygiene. Put keys in environment variables or secret stores, never in committed files. Create one key per machine or integration so you can revoke them independently.

Access and request budgets​

Cloud API, CLI, and MCP access is included in Team (1,000 requests/hour per workspace), Business (5,000/hour), and Enterprise (no plan-based hourly ceiling). Free and Personal return 403 plan_forbidden. The account budget is shared across all its keys. Self-hosted installations do not apply the cloud plan gate and may configure their own rate limits.

Limited accounts receive RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds). A 429 rate_limited response includes Retry-After; honor it before retrying. A separate per-IP abuse limit also applies. An entitlement lookup failure returns retryable 503 entitlement_unavailable, not a plan denial.

The current key contract scopes access to its workspace and requires the creator's membership. It does not expose a per-project or read-only scope selector. .testvibe.json can store server/project defaults but cannot supply an API key.