Authentication

Authentication

All API requests require an Authorization header with a Bearer token.

Authorization: Bearer vb_live_01j...

API key prefixes

Prefix	Environment	Use
vb_live_	Production	All production traffic
vb_test_	Sandbox	Development and testing; no real KMS calls

Never use vb_test_ keys in production. Never embed any key in client-side code.

Key scopes

Scope	Permitted endpoints
sign	POST /v1/sign, GET /v1/jobs/{job_id}, POST /v1/lookup, GET /v1/recipes, GET /v1/usage
verify	POST /v1/verify, GET /v1/verify/{manifest_id}, POST /v1/lookup
admin	All sign + verify endpoints, plus: POST /v1/recipes, POST /v1/keys, GET /v1/audit, GET /v1/usage (tenant-wide), GET/PUT/DELETE /v1/cms/*

The agent self-onboard endpoint (POST /v1/onboard) mints a sign-scoped key by default. Scope elevation to admin requires an explicit admin action in the dashboard or via POST /v1/keys.

Rate limits by plan

Plan	Requests/second	Requests/day	Requests/month
Free	1	100	500
Developer	5	1,000	10,000
Growth	20	10,000	100,000
Enterprise	Custom	Custom	Custom

Rate limit headers are returned on every response:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1715248800

When a limit is exceeded, the API returns 429 with a Retry-After header. SDKs retry automatically with exponential backoff (max 3 attempts).

Getting an API key

1. Sign up at verbitas.io/signup (humans). Programmatic onboarding uses POST /v1/onboard below.
2. After completing onboarding, your initial sign-scoped key is shown once. Store it immediately — it is never shown again.
3. Additional keys can be created in the admin console at verbitas.io/admin/keys.

For autonomous agents and CI pipelines:

curl -X POST https://api.verbitas.io/v1/onboard \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(python3 -c 'import uuid; print(uuid.uuid4())')" \
  -H "User-Agent: my-pipeline/1.0" \
  -d '{
    "email": "[email protected]",
    "payment_method_token": "pm_...",
    "plan": "developer"
  }'

The response includes api_key once. See Guides: Enterprise Onboarding for multi-tenant setup.

Idempotency

All mutating endpoints (POST /v1/sign, POST /v1/recipes, POST /v1/onboard) require an Idempotency-Key header. Use a UUIDv7 generated fresh for each logical request.

Idempotency-Key: 01926e7a-f2b3-7abc-8def-0123456789ab

Requests with the same Idempotency-Key and identical payload are deduplicated for 7 days (Redis TTL). Requests with the same key but different payload return 409 verbitas.sign.idempotency_conflict.

Environment variable

All SDKs and the MCP server read the key from VERBITAS_API_KEY:

export VERBITAS_API_KEY=vb_live_01j...

Never pass keys as command-line arguments or log them.