Authentication - Velobase

Velobase is an AI gateway first: point your OpenAI or Anthropic SDK at https://api.velobase.io/v1 and bill every model call to an end-customer’s wallet. It is also a billing ledger (freeze, consume, deduct) for work you price yourself. Both surfaces share the same API keys. Velobase uses API keys to authenticate requests. You can create and manage API keys from your dashboard under the Keys section of any project.

Bearer Token

Provide your API key in the Authorization HTTP header using the Bearer scheme.

Authorization: Bearer <your_api_key_here>

Example Request

To verify a key is working, call an authenticated endpoint such as GET /v1/models. (The unauthenticated /health endpoint does not require a key.)

curl https://api.velobase.io/v1/models \
  -H "Authorization: Bearer vb_live_1234567890abcdef"

Key Types

Velobase issues two kinds of API keys, distinguished by their prefix:

Project key (vb_live_): A server-side key for your backend. It is not bound to any single customer, so billable requests must name the customer to charge with the X-Velobase-Customer: <user-id> header.
Customer-scoped key (vb_customer_): A key bound to one of your customers. It carries its own customer binding, so no header is needed. These keys can be restricted to an allowedModels whitelist and given an expiresAt.

# Project key: pass the customer to bill via header
curl https://api.velobase.io/v1/chat/completions \
  -H "Authorization: Bearer vb_live_1234567890abcdef" \
  -H "X-Velobase-Customer: user_42" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4-pro", "messages": [{"role": "user", "content": "Hello"}]}'

# Customer-scoped key: customer is implied, no header needed
curl https://api.velobase.io/v1/chat/completions \
  -H "Authorization: Bearer vb_customer_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4-pro", "messages": [{"role": "user", "content": "Hello"}]}'

Non-billable endpoints like GET /v1/models do not require a customer. Billable endpoints (such as /v1/chat/completions and /v1/messages) need a resolvable customer, from the header or the key binding, or they return a 400.

Key Scoping

Project Isolation: Every API key is scoped to a specific project. An API key created in Project A cannot access customers in Project B.
Roll and Revoke: You can revoke an API key at any time from the dashboard if you suspect it has been compromised. Requests using a revoked key will immediately start failing with an api_key_revoked error.

Authentication Errors

If your request cannot be authenticated, Velobase returns a 401 Unauthorized status code.

Error Code	Reason
`missing_api_key`	The `Authorization` header is missing.
`invalid_api_key`	The provided key is malformed, incorrect, or belongs to a deleted project.
`api_key_revoked`	The key has been manually revoked in the dashboard.

For more details on error formats, see Handling Errors.

​Bearer Token

​Example Request

​Key Types

​Key Scoping

​Authentication Errors

Bearer Token

Example Request

Key Types

Key Scoping

Authentication Errors