API Keys

API key products let you sell access to your own APIs or services. After purchase, the customer receives a unique key that your application can validate against FOSSBilling.

Tip

This extension is included with FOSSBilling since version 0.5.3. Enable it from Extensions → API Key Product.

Caution

Disabling or removing this extension will delete the database table storing API keys. Make sure to back up your data first.

Use Cases

• Sell access to your REST API
• Limit requests per customer
• Offer tiered plans with different limits
• Track usage per customer

Setting Up API Key Products

1. Enable the Extension

   Go to Extensions and install "API Key Product".

2. Configure Key Generation

   When creating the product, set these options:

   Option	Default	Description
   Length	32	Total characters in the key
   Split	Enabled	Add dashes for readability
   Split Interval	8	Characters between dashes
   Capitalization	Uppercase	Uppercase, lowercase, or mixed

   Example key with default settings:

   BA907863-47C1A4F5-3CB914D3-AC927BDD

   Note

   Dashes don't count toward the key length. If you disable splitting, the key would be BA90786347C1A4F53CB914D3AC927BDD.

3. Add Custom Parameters

   You can define custom parameters attached to each API key:

   • monthlyLimit — number of allowed requests per month
   • tier — pricing tier (basic, pro, enterprise)
   • Any other metadata your application needs

   Danger

   Custom parameters are retrievable by anyone with the API key. Don't store sensitive information here.

API Endpoints

Endpoint	Access	Description
/admin/serviceapikey/update	Admin	Update API key config and validity
/admin/serviceapikey/reset	Admin	Regenerate a new API key
/client/serviceapikey/reset	Client	Customer resets their own key
/guest/serviceapikey/check	Guest	Check if a key is valid
/guest/serviceapikey/get_info	Guest	Get key validity + custom parameters

Checking Key Validity

curl -X POST "https://your-fossbilling.com/api/guest/serviceapikey/check" \
  -H "Content-Type: application/json" \
  -d '{"key": "BA907863-47C1A4F5-3CB914D3-AC927BDD"}'

Response:

{
  "result": true,
  "error": null
}

Getting Key Info (with custom params)

curl -X POST "https://your-fossbilling.com/api/guest/serviceapikey/get_info" \
  -H "Content-Type: application/json" \
  -d '{"key": "BA907863-47C1A4F5-3CB914D3-AC927BDD"}'

Response:

{
  "result": {
    "valid": 1,
    "config": {
      "monthlyLimit": 250,
      "tier": "pro"
    }
  },
  "error": null
}

Rate Limiting

FOSSBilling includes rate limiting on all API requests (configured via the rate_limiter config block in 0.8.0+). This prevents brute-force attacks on your /check endpoints.

Tip

Cache validation results in your application for a few minutes. This avoids hitting rate limits and reduces server load.

You can adjust rate limiting in the configuration.

Security Considerations

• Clients can reset their keys — they see and can regenerate their own API keys
• To revoke access, change the key's validity rather than resetting it
• Validate keys server-side — don't trust client-side checks
• Use HTTPS — always encrypt API key traffic