API Keys

Manage API keys for programmatic access to BrewHoard features with granular permissions.

API keys provide programmatic access to BrewHoard’s features. Keys are prefixed with bv_live_ for production or bv_test_ for testing environments.

Creating API Keys

Create a new API key with specific permissions:

JavaScript
import { createApiKey } from '$lib/auth/api-keys.js';

const { id, key } = await createApiKey(userId, 'My App', {
    collection: { read: true, write: true },
    marketplace: { read: true }
});

// Store the 'key' securely - it won't be shown again

Key Format

API keys follow the format: bv_live_[32-character-hex] or bv_test_[32-character-hex]

  • bv_live_: Production keys with full access
  • bv_test_: Test keys with limited permissions

Scopes and Permissions

API keys have granular permissions for different modules:

ModuleReadWriteDeleteDescription
collection✓✓✓Beer collection management
marketplace✓✓✓Marketplace listings and transactions
ratings✓✓-Beer ratings and reviews
analytics✓--Usage analytics and statistics
admin✓✓-Administrative functions

Key Rotation

Rotate keys regularly for security:

JavaScript
// Create new key with same permissions
const newKey = await createApiKey(userId, 'My App v2', oldKey.permissions);

// Update your application with new key
// Then revoke old key
await revokeApiKey(oldKey.id, userId);

Revoking Keys

Revoke a key to immediately disable access:

JavaScript
import { revokeApiKey } from '$lib/auth/api-keys.js';

await revokeApiKey(keyId, userId);

Usage Tracking

Track API key usage with timestamps:

JavaScript
// Keys automatically update last_used_at on each request
const keys = await getUserApiKeys(userId);
console.log(keys[0].last_used_at); // Last usage timestamp

Best Practices

  • Store keys securely, never in version control
  • Use test keys for development
  • Rotate keys regularly (every 30-90 days)
  • Monitor usage patterns
  • Use minimal required permissions
  • Revoke keys immediately when compromised

Next Steps