Authentication

ModelBridge uses API keys to authenticate all proxy requests. Every request must include a valid key in the Authorization header.

API keys

API keys are created from your ModelBridge dashboard. Each key:

• Starts with mb_ followed by a random string
• Is hashed with SHA-256 before storage -- ModelBridge never stores your raw key
• Can be scoped to a specific team or used as a personal key
• Can have an optional spending limit and expiration date

Sending requests

Include your API key in the Authorization header using the Bearer scheme:

curl https://api.modelbridge.dev/v1/chat/completions \
  -H "Authorization: Bearer mb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "messages": [{"role": "user", "content": "Hello"}]}'

With the OpenAI SDK, pass it as the api_key parameter:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.modelbridge.dev/v1",
    api_key="mb_live_your_key_here",
)

Key types

Personal keys

Created from your personal dashboard. Spend is charged to your personal balance. These keys are tied to your user account.

Team keys

Created within a team context. Spend is charged to the team's shared balance. Any team member with appropriate permissions can create team keys.

To create a team key, select the team from the dropdown when creating a new API key in the dashboard.

Key management

Spending limits

Each key can have an optional spending limit in AUD. When the limit is reached, the key returns a 429 error. This is useful for:

• Limiting exposure from a leaked key
• Budget control on per-project keys
• Preventing runaway costs from automated workflows

Expiration

Keys can be set to expire at a specific date. Expired keys return a 401 error.

Revocation

You can revoke a key at any time from the dashboard. Revoked keys immediately stop working and cannot be restored.

Security best practices

• Never commit keys to version control. Use environment variables or a secrets manager.
• Use spending limits on all keys, especially those used in automated pipelines.
• Rotate keys regularly and revoke unused ones.
• Use team keys for shared projects instead of sharing personal keys.
• Set expiration dates for temporary access or contractor keys.

Environment variables

The recommended way to configure your API key:

# Add to ~/.bashrc, ~/.zshrc, or your CI/CD environment
export OPENAI_API_KEY="mb_live_your_key_here"
export OPENAI_BASE_URL="https://api.modelbridge.dev/v1"

Most OpenAI-compatible SDKs and tools read OPENAI_API_KEY and OPENAI_BASE_URL automatically.