Skip to main content

API Keys

API Keys are the primary method for authenticating with the Billoget API. This guide covers everything you need to know about creating, managing, and using API keys.

🔑 What are API Keys?​

API Keys are secure tokens that identify your application and determine what actions it can perform. Each key has:

  • Unique identifier: A secure, randomly generated string
  • Scopes: Specific permissions for different operations
  • Rate limits: Request limits per hour
  • Security settings: IP whitelisting, expiration dates
  • Usage tracking: Detailed analytics and logging

🏗️ Creating API Keys​

Step 1: Authenticate with Billoget​

First, you need to authenticate with your Billoget account to create API keys:

curl -X POST "https://api.billoget.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

Step 2: Create an API Key​

Use your JWT token to create a new API key:

curl -X POST "https://api.billoget.com/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My E-commerce Integration",
    "description": "API key for Shopify integration",
    "scopes": ["READ_BUDGETS", "WRITE_BUDGETS", "READ_CUSTOMERS", "WRITE_CUSTOMERS"],
    "rateLimitPerHour": 1000,
    "allowedIps": ["192.168.1.100", "10.0.0.50"],
    "expiresAt": "2024-12-31T23:59:59Z",
    "webhookUrl": "https://myapp.com/webhooks/billoget"
  }'

Response​

{
  "id": "api_key_123",
  "name": "My E-commerce Integration",
  "key": "bk_live_1234567890abcdef1234567890abcdef",
  "keyPrefix": "bk_live_1234",
  "scopes": [
    "READ_BUDGETS",
    "WRITE_BUDGETS",
    "READ_CUSTOMERS",
    "WRITE_CUSTOMERS"
  ],
  "rateLimitPerHour": 1000,
  "status": "ACTIVE",
  "allowedIps": ["192.168.1.100", "10.0.0.50"],
  "expiresAt": "2024-12-31T23:59:59Z",
  "webhookUrl": "https://myapp.com/webhooks/billoget",
  "createdAt": "2024-01-15T10:30:00Z"
}
Important

The full API key is only shown once during creation. Store it securely - you won't be able to retrieve it again!

📊 API Key Properties​

Required Properties​

PropertyTypeDescription
namestringHuman-readable name for the API key
scopesarrayList of permissions for the key

Optional Properties​

PropertyTypeDefaultDescription
descriptionstringnullDetailed description of the key's purpose
rateLimitPerHournumber1000Maximum requests per hour
allowedIpsarraynullIP addresses allowed to use this key
expiresAtstringnullExpiration date (ISO 8601 format)
webhookUrlstringnullURL for webhook notifications
webhookSecretstringauto-generatedSecret for webhook signature validation

🎯 Scopes and Permissions​

Available Scopes​

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

Scope Examples​

// Read-only access to budgets and customers
const readOnlyScopes = ["READ_BUDGETS", "READ_CUSTOMERS"];

// Full access to budgets only
const budgetScopes = ["READ_BUDGETS", "WRITE_BUDGETS"];

// Complete access to all resources
const fullScopes = [
  "READ_BUDGETS",
  "WRITE_BUDGETS",
  "READ_CUSTOMERS",
  "WRITE_CUSTOMERS",
  "READ_PRODUCTS",
  "WRITE_PRODUCTS",
  "WEBHOOKS",
];

🔧 Managing API Keys​

List All API Keys​

curl -X GET "https://api.billoget.com/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Specific API Key​

curl -X GET "https://api.billoget.com/api-keys/api_key_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update API Key​

curl -X PUT "https://api.billoget.com/api-keys/api_key_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Integration Name",
    "status": "ACTIVE",
    "rateLimitPerHour": 2000
  }'

Delete API Key​

curl -X DELETE "https://api.billoget.com/api-keys/api_key_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

📈 Usage Analytics​

Get Usage Statistics​

curl -X GET "https://api.billoget.com/api-keys/api_key_123/stats?period=7d" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response​

{
  "period": "7d",
  "totalRequests": 2450,
  "successfulRequests": 2380,
  "errorRequests": 70,
  "averageResponseTime": 245,
  "topEndpoints": [
    {
      "endpoint": "/api/public/budgets",
      "method": "GET",
      "count": 1200
    },
    {
      "endpoint": "/api/public/customers",
      "method": "POST",
      "count": 800
    }
  ],
  "dailyUsage": [
    {
      "date": "2024-01-15",
      "requests": 350
    },
    {
      "date": "2024-01-16",
      "requests": 420
    }
  ]
}

Available Periods​

  • 1h - Last hour
  • 24h - Last 24 hours
  • 7d - Last 7 days
  • 30d - Last 30 days
  • 90d - Last 90 days

🔒 Security Features​

IP Whitelisting​

Restrict API key usage to specific IP addresses:

{
  "allowedIps": ["192.168.1.100", "10.0.0.50", "203.0.113.0/24"]
}

Expiration Dates​

Set automatic expiration for API keys:

{
  "expiresAt": "2024-12-31T23:59:59Z"
}

Key Status Management​

API keys can have different statuses:

  • ACTIVE - Key is active and can be used
  • SUSPENDED - Key is temporarily disabled
  • REVOKED - Key is permanently disabled

🚨 API Key Status​

Status Codes​

StatusDescriptionCan be used?
ACTIVEKey is active and working✅ Yes
SUSPENDEDKey is temporarily disabled❌ No
REVOKEDKey is permanently disabled❌ No

Checking Key Status​

curl -X GET "https://api.billoget.com/api-keys/api_key_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

🛠️ Code Examples​

JavaScript/Node.js​

class BillogetAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = "https://api.billoget.com/v1";
  }

  async createApiKey(keyData) {
    const response = await fetch(`${this.baseUrl}/api-keys`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${this.jwtToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(keyData),
    });

    return response.json();
  }

  async getApiKeyStats(keyId, period = "7d") {
    const response = await fetch(
      `${this.baseUrl}/api-keys/${keyId}/stats?period=${period}`,
      {
        headers: {
          Authorization: `Bearer ${this.jwtToken}`,
        },
      }
    );

    return response.json();
  }
}

Python​

import requests
import json

class BillogetAPI:
    def __init__(self, jwt_token):
        self.jwt_token = jwt_token
        self.base_url = 'https://api.billoget.com/v1'
        self.headers = {
            'Authorization': f'Bearer {jwt_token}',
            'Content-Type': 'application/json'
        }

    def create_api_key(self, key_data):
        response = requests.post(
            f'{self.base_url}/api-keys',
            headers=self.headers,
            json=key_data
        )
        return response.json()

    def get_api_key_stats(self, key_id, period='7d'):
        response = requests.get(
            f'{self.base_url}/api-keys/{key_id}/stats?period={period}',
            headers=self.headers
        )
        return response.json()

⚠️ Best Practices​

1. Use Minimal Scopes​

Only grant the scopes your application actually needs:

{
  "scopes": ["READ_BUDGETS", "READ_CUSTOMERS"]
}

2. Set Appropriate Rate Limits​

Don't request more than you need:

{
  "rateLimitPerHour": 500
}

3. Use IP Whitelisting in Production​

Restrict access to known IP addresses:

{
  "allowedIps": ["203.0.113.100"]
}

4. Set Expiration Dates​

Use expiration dates for temporary integrations:

{
  "expiresAt": "2024-06-30T23:59:59Z"
}

5. Monitor Usage Regularly​

Check usage statistics frequently:

curl -X GET "https://api.billoget.com/api-keys/api_key_123/stats?period=24h"

🚀 Next Steps​

Now that you understand API keys, let's learn about:

  1. Rate Limiting - Understanding request limits
  2. Error Handling - Handling API errors gracefully
  3. API Reference - Explore available endpoints

📚 Additional Resources​

Ready to learn about rate limiting? Let's go to Rate Limiting! ⚡