Authentication

Ballast supports two authentication methods: API keys for programmatic access and JWT tokens for browser-based sessions.

API Keys

API keys are the recommended method for integrations, scripts, and MCP clients.

Creating API Keys

1. Open your collection in the Ballast dashboard
2. Go to Settings → API Keys
3. Click Create API Key
4. Name it and copy the key immediately—it’s shown only once

Key Format

API keys use the bk_ prefix:

bk_abc123def456...

Keys are stored as bcrypt hashes. Ballast cannot recover your key after creation—if lost, create a new one.

Using API Keys

Include your key in the Authorization header with the Bearer prefix:

curl https://api.ballast.sh/v1/search 
  -H "Authorization: Bearer bk_your_api_key" 
  -H "Content-Type: application/json" 
  -d '{"query": "quarterly report", "collectionId": "..."}'

API Key Scopes

Keys can be scoped to limit access:

Scope	Access
Collection	Single collection only
Organization	All collections in the org
User	Includes the user’s personal sources

Collection-scoped keys are recommended for MCP integrations—they limit exposure if a key is compromised.

Organization-scoped keys can access all collections and are useful for admin tools.

User-scoped keys include personal sources (Gmail, personal Google Drive) that the creating user has connected.

Key Lifecycle

Field	Description
is_active	Whether the key is usable
expires_at	Optional expiration timestamp
last_used_at	Auto-updated on each use

Revoke keys anytime from the dashboard. Revoked keys immediately stop working.

JWT Authentication

The web application uses JWT tokens for session management.

Login Flow

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "..."
}

Response:

{
  "token": "eyJ...",
  "refreshToken": "eyJ...",
  "user": {
    "id": "...",
    "email": "user@example.com",
    "name": "..."
  }
}

Using JWT Tokens

Include the token in the Authorization header:

Authorization: Bearer eyJ...

Token Refresh

Tokens expire after a period. Use the refresh endpoint to get a new token:

POST /api/v1/auth/refresh
Authorization: Bearer <refresh_token>

Authentication Errors

Status	Error	Description
401	unauthorized	Missing or invalid token/key
401	key_revoked	API key has been revoked
401	key_expired	API key has expired
403	forbidden	Key doesn’t have access to this resource
403	collection_denied	Collection-scoped key used on wrong collection

MCP Authentication

MCP endpoints accept either API keys or JWT tokens.

For Claude Desktop and other MCP clients, use API keys:

{
  "mcpServers": {
    "ballast": {
      "url": "https://api.ballast.sh/mcp/collections/my-collection",
      "headers": {
        "Authorization": "Bearer bk_my_api_key"
      }
    }
  }
}

For the web app’s internal MCP usage, JWT tokens work automatically.

Security Best Practices

Store keys securely

• Use environment variables, not hardcoded values
• Never commit keys to version control
• Use secrets management in CI/CD

Use minimal scopes

• Create collection-scoped keys when possible
• Only use org-scoped keys for admin tools

Rotate regularly

• Create new keys periodically
• Revoke unused keys
• Check last_used_at to identify stale keys

Monitor usage

• Review API key usage in the dashboard
• Set expiration dates for temporary access
• Revoke immediately if compromise is suspected

Rate Limits

API requests are rate-limited per key. Limits depend on your plan:

Plan	Requests/minute
Free	60
Pro	300
Enterprise	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1699574400