API Key Scoping

API keys in Ballast can be scoped to limit what data they can access. This reduces risk if a key is compromised.

Key Scopes

Collection Scope

Keys limited to a single collection:

Scope: collection:col_abc123
Access: Only that collection's data

Best for:

• MCP connections to Claude Desktop
• Collection-specific integrations
• External partner access

Create in: Collection settings → API Keys

Organization Scope

Keys that access all collections in the organization:

Scope: organization
Access: All collections, no personal sources

Best for:

• Admin tools
• Internal dashboards
• Cross-collection integrations

Create in: Organization settings → API Keys

User Scope

Keys that include the creating user’s personal sources:

Scope: user:usr_xyz789
Access: All collections + user's personal sources

Best for:

• MCP connections needing personal data (Gmail, etc.)
• User-specific applications

Create in: Collection settings → API Keys (select “Include my personal sources”)

Choosing a Scope

Use Case	Recommended Scope
Claude Desktop	Collection
MCP with personal data	User
Backend service	Organization
External partner	Collection
Admin tool	Organization

Key Format

All keys use the bk_ prefix:

bk_a1b2c3d4e5f6...

Keys are 32+ characters and stored as bcrypt hashes. They cannot be recovered after creation.

Key Metadata

Each key tracks:

Field	Description
name	Descriptive name
created_at	Creation timestamp
last_used_at	Last API call
expires_at	Optional expiration
is_active	Whether key is usable

Expiration

Keys can have optional expiration dates:

• Set during creation
• After expiration, key stops working
• Useful for temporary access

Revoking Keys

To revoke a key:

1. Go to the settings where you created it
2. Find the key by name
3. Click Revoke

Revocation is immediate. The key stops working instantly.

Best Practices

Use minimal scope

• Start with collection scope
• Only use broader scopes when needed

Set expiration for temporary access

• Contractor access
• Demo environments
• Testing

Name keys descriptively

• “Claude Desktop - Engineering”
• “CI/CD Pipeline”
• “Partner Integration - Acme”

Review regularly

• Check last_used_at for stale keys
• Revoke unused keys
• Audit key list quarterly