Authentication

The Bookovia Telematics API uses API key authentication for secure access to all endpoints. This guide covers everything you need to know about managing and using API keys effectively.

API Key Format

Bookovia API keys follow a specific format for easy identification and environment management:

Format: {prefix}_{environment}_{key}

Examples:
bkv_test_1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890  # Test
bkv_live_9z8y7x6w5v4u3t2s1r0q9p8o7n6m5l4k3j2i1h0g9f8e7d6c5b4a3z2y1x0w9v8u  # Production

Key Components

Prefix: bkv (Bookovia identifier)
Environment: test or live
Key: 64-character hexadecimal string

Generating API Keys

From Dashboard

Log in to dashboard.bookovia.com
Navigate to Settings → API Keys
Click “Generate New Key”
Choose environment:
- test for development and testing
- live for production use
Name your key (e.g., “Mobile App”, “Backend Service”)
Set permissions and rate limits
Copy the generated key immediately

API keys are only shown once during generation. Store them securely and never expose them in client-side code.

Via API (Enterprise)

Enterprise customers can generate keys programmatically:

curl -X POST https://api.bookovia.com/v1/api-keys \
  -H "X-API-Key: bkv_live_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Service Key",
    "environment": "live",
    "rate_limit_rpm": 1000,
    "permissions": ["trips:read", "trips:write", "analytics:read"]
  }'

Using API Keys

HTTP Header Authentication

Include your API key in the X-API-Key header for all requests:

curl -H "X-API-Key: bkv_test_your_api_key_here" \
     https://api.bookovia.com/v1/trips

SDK Authentication

Our client SDKs handle authentication automatically:

import Bookovia from '@bookovia/javascript-sdk';

const client = new Bookovia('bkv_test_your_api_key_here');
// All subsequent requests are automatically authenticated

Environment Management

Test Environment

Use bkv_test_* keys for:

✅ Development and testing
✅ Integration testing
✅ Staging environments
✅ Learning and experimentation

Characteristics:

Separate data isolation from production
Higher rate limits for testing (1000 RPM default)
Mock data and synthetic responses available
No billing for API usage

Production Environment

Use bkv_live_* keys for:

✅ Production applications
✅ Live customer data
✅ Real vehicle tracking
✅ Production dashboards

Characteristics:

Real-time data processing
Production SLA (99.9% uptime)
Usage-based billing
Enhanced monitoring and support

Always use test keys during development and only switch to live keys when deploying to production.

Security Best Practices

Storage & Handling

✅ DO: Store in Environment Variables

# .env file
BOOKOVIA_API_KEY=bkv_live_your_production_key

# In your application
const apiKey = process.env.BOOKOVIA_API_KEY;

✅ DO: Use Secret Management

// AWS Secrets Manager
const secret = await secretsManager.getSecretValue({
  SecretId: 'bookovia-api-key'
}).promise();

const apiKey = JSON.parse(secret.SecretString).apiKey;

❌ DON'T: Hardcode in Source

// Never do this!
const apiKey = 'bkv_live_1234567890abcdef...';

❌ DON'T: Expose in Client-Side Code

<!-- Never expose in frontend -->
<script>
  const apiKey = 'bkv_live_1234567890abcdef...';
</script>

Access Control

Principle of Least Privilege: Grant minimum required permissions
Regular Rotation: Rotate keys every 90 days
Environment Isolation: Use separate keys for each environment
Team Management: Individual keys per team member when possible

Monitoring

Usage Tracking: Monitor API key usage patterns
Anomaly Detection: Alert on unusual usage spikes
Access Logging: Log all API key usage
Rate Limit Monitoring: Track rate limit consumption

Rate Limiting

API keys have built-in rate limiting to ensure fair usage:

Default Limits

Plan	Requests per Minute	Burst Limit
Starter	100 RPM	200
Professional	500 RPM	1,000
Enterprise	2,000 RPM	5,000
Custom	Negotiable	Negotiable

Rate Limit Headers

Every response includes rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1713024000
X-RateLimit-Window: 60

Handling Rate Limits

Implement exponential backoff when you hit limits:

async function makeRequestWithBackoff(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status !== 429) {
      return response;
    }
    
    if (attempt === maxRetries) {
      throw new Error('Rate limit exceeded');
    }
    
    const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
    await new Promise(resolve => setTimeout(resolve, delay));
  }
}

Error Handling

Authentication Errors

Status Code	Error	Description	Solution
401	`invalid_api_key`	API key format is invalid	Check key format and regenerate if needed
401	`api_key_not_found`	API key doesn’t exist	Verify key exists in dashboard
401	`api_key_revoked`	API key has been revoked	Generate a new API key
403	`insufficient_permissions`	Key lacks required permissions	Update key permissions
429	`rate_limit_exceeded`	Rate limit exceeded	Implement exponential backoff

Example Error Responses

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key format is invalid",
    "details": "API keys must start with 'bkv_' followed by environment and 64-char hex string"
  },
  "request_id": "req_1234567890abcdef"
}

Key Management

Rotation Strategy

Generate new API key
Update one service at a time
Monitor for successful requests
Revoke old key after 48 hours

Permissions Model

API keys support granular permissions:

{
  "permissions": [
    "trips:read",
    "trips:write", 
    "locations:write",
    "analytics:read",
    "fleet:read",
    "devices:manage"
  ]
}

Monitoring Dashboard

Track key usage in your dashboard:

Request Volume: Requests per minute/hour/day
Error Rates: Failed authentication attempts
Geographic Distribution: Request origins
Endpoint Usage: Most-used API endpoints

Troubleshooting

Common Issues

401 Unauthorized

Cause: Invalid or missing API keySolutions:

Verify API key format (bkv_test_* or bkv_live_*)
Check for typos in the key
Ensure key exists in dashboard
Verify key hasn’t been revoked

403 Forbidden

Cause: Insufficient permissionsSolutions:

Check key permissions in dashboard
Verify you’re using the correct environment key
Contact admin to update permissions

429 Rate Limited

Cause: Exceeded rate limitSolutions:

Implement exponential backoff
Reduce request frequency
Consider upgrading your plan
Cache responses when possible

Debug Mode

Enable debug logging to troubleshoot authentication issues:

const client = new Bookovia('your-api-key', {
  debug: true,
  logLevel: 'debug'
});

Next Steps

Now that you understand authentication:

Make Your First Request

Follow our quickstart guide to make your first authenticated request

Explore API Endpoints

Browse our comprehensive API reference documentation

Use Client SDKs

Get started with our production-ready client SDKs

Integration Examples

See real-world integration examples and best practices

Need help with authentication? Contact our support team at support@bookovia.com

Get Started

Core Concepts

Integration Guides

Authentication

Authentication

API Key Format

Key Components

Generating API Keys

From Dashboard

Via API (Enterprise)

Using API Keys

HTTP Header Authentication

SDK Authentication

Environment Management

Test Environment

Production Environment

Security Best Practices

Storage & Handling

Access Control

Monitoring

Rate Limiting

Default Limits

Rate Limit Headers

Handling Rate Limits

Error Handling

Authentication Errors

Example Error Responses

Key Management

Rotation Strategy

Permissions Model

Monitoring Dashboard

Troubleshooting

Common Issues

Debug Mode

Next Steps

Make Your First Request

Explore API Endpoints

Use Client SDKs

Integration Examples

Get Started

Core Concepts

Integration Guides

Documentation Index

​Authentication

​API Key Format

​Key Components

​Generating API Keys

​From Dashboard

​Via API (Enterprise)

​Using API Keys

​HTTP Header Authentication

​SDK Authentication

​Environment Management

​Test Environment

​Production Environment

​Security Best Practices

​Storage & Handling

​Access Control

​Monitoring

​Rate Limiting

​Default Limits

​Rate Limit Headers

​Handling Rate Limits

​Error Handling

​Authentication Errors

​Example Error Responses

​Key Management

​Rotation Strategy

​Permissions Model

​Monitoring Dashboard

​Troubleshooting

​Common Issues

​Debug Mode

​Next Steps

Make Your First Request

Explore API Endpoints

Use Client SDKs

Integration Examples

Authentication

API Key Format

Key Components

Generating API Keys

From Dashboard

Via API (Enterprise)

Using API Keys

HTTP Header Authentication

SDK Authentication

Environment Management

Test Environment

Production Environment

Security Best Practices

Storage & Handling

Access Control

Monitoring

Rate Limiting

Default Limits

Rate Limit Headers

Handling Rate Limits

Error Handling

Authentication Errors

Example Error Responses

Key Management

Rotation Strategy

Permissions Model

Monitoring Dashboard

Troubleshooting

Common Issues

Debug Mode

Next Steps