Skip to main content

Authentication

The Billoget API uses API Keys for authentication. This guide will walk you through how authentication works and how to use it in your applications.

🔐 Authentication Method​

API Key Authentication​

All API requests must include an API key in the Authorization header using the Bearer token format:

Authorization: Bearer bk_live_1234567890abcdef...

No Session Management​

Unlike traditional web applications, the API is stateless. Each request must include the API key - there's no session management or cookie handling required.

🔑 API Key Format​

API keys follow a specific format to ensure security and easy identification:

bk_live_1234567890abcdef1234567890abcdef

Format breakdown:

  • bk_ - Billoget prefix
  • live_ - Environment indicator (live/test)
  • 1234567890abcdef... - Random secure token

🎯 Scopes and Permissions​

Each API key has specific scopes that determine what actions it can perform:

Available Scopes​

ScopeDescriptionEndpoints
READ_BUDGETSRead budget dataGET /api/public/budgets
WRITE_BUDGETSCreate/update budgetsPOST/PUT/DELETE /api/public/budgets
READ_CUSTOMERSRead customer dataGET /api/public/customers
WRITE_CUSTOMERSCreate/update customersPOST/PUT/DELETE /api/public/customers
READ_PRODUCTSRead product dataGET /api/public/products
WRITE_PRODUCTSCreate/update productsPOST/PUT/DELETE /api/public/products
WEBHOOKSReceive webhooksPOST /api/public/webhooks/test

Scope Validation​

When you make a request, the API checks if your API key has the required scope:

{
  "error": "insufficient_scope",
  "message": "API key does not have required scope: WRITE_BUDGETS"
}

🛠️ Making Authenticated Requests​

Basic Request Structure​

curl -X GET "https://api.billoget.com/v1/api/public/budgets" \
  -H "Authorization: Bearer bk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

JavaScript Example​

const apiKey = "bk_live_1234567890abcdef";
const baseUrl = "https://api.billoget.com/v1";

const headers = {
  Authorization: `Bearer ${apiKey}`,
  "Content-Type": "application/json",
};

// GET request
const response = await fetch(`${baseUrl}/api/public/budgets`, {
  method: "GET",
  headers: headers,
});

const data = await response.json();

Python Example​

import requests

api_key = 'bk_live_1234567890abcdef'
base_url = 'https://api.billoget.com/v1'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

# GET request
response = requests.get(f'{base_url}/api/public/budgets', headers=headers)
data = response.json()

PHP Example​

<?php
$apiKey = 'bk_live_1234567890abcdef';
$baseUrl = 'https://api.billoget.com/v1';

$headers = [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
];

// GET request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/api/public/budgets');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
?>

🔒 Security Best Practices​

1. Keep API Keys Secret​

  • Never expose API keys in client-side code
  • Store keys in environment variables or secure configuration
  • Use different keys for different environments

2. Use HTTPS Only​

  • All API requests must use HTTPS
  • Never send API keys over HTTP

3. Rotate Keys Regularly​

  • Regenerate API keys periodically
  • Have a key rotation strategy in place
  • Monitor key usage for unusual activity

4. Implement IP Whitelisting​

  • Restrict API key usage to specific IP addresses
  • Use this feature for production environments

5. Monitor Usage​

  • Track API key usage regularly
  • Set up alerts for unusual activity
  • Review access logs periodically

❌ Common Authentication Errors​

401 Unauthorized​

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Causes:

  • Missing Authorization header
  • Invalid API key format
  • Expired or revoked API key

403 Forbidden​

{
  "error": "insufficient_scope",
  "message": "API key does not have required scope: WRITE_BUDGETS"
}

Causes:

  • API key doesn't have required scope
  • IP address not whitelisted
  • API key suspended

429 Too Many Requests​

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 3600 seconds"
}

Causes:

  • Exceeded rate limit for the API key
  • Too many requests in short time period

🧪 Testing Authentication​

Test API Key Validity​

curl -X GET "https://api.billoget.com/v1/api/public/budgets?limit=1" \
  -H "Authorization: Bearer bk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

Expected Response​

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 0,
    "hasMore": false
  }
}

🔄 Environment-Specific Keys​

Development vs Production​

  • Use bk_test_ prefixed keys for development
  • Use bk_live_ prefixed keys for production
  • Never use production keys in development

Key Management​

// Environment-specific configuration
const config = {
  development: {
    apiKey: "bk_test_1234567890abcdef",
    baseUrl: "https://api.billoget.com/v1",
  },
  production: {
    apiKey: "bk_live_1234567890abcdef",
    baseUrl: "https://api.billoget.com/v1",
  },
};

const env = process.env.NODE_ENV || "development";
const apiConfig = config[env];

🚀 Next Steps​

Now that you understand authentication, let's learn about:

  1. API Keys - How to create and manage API keys
  2. Rate Limiting - Understanding rate limits
  3. Error Handling - Handling API errors gracefully

📚 Additional Resources​

Ready to create your first API key? Let's go to API Keys! 🔑