API Reference

This reference describes how to interact with the official FOSSBilling API.

If you’re developing a module or theme, avoid making direct API calls. Use the JavaScript wrapper instead, which provides a streamlined way to communicate with the backend.

A comprehensive API guide is currently in progress. Meanwhile, since there have been no major breaking changes since the last BoxBilling release, you can also refer to the BoxBilling API documentation for additional reference.

API endpoints

FOSSBilling provides 3 main API entrypoints:

example.com/api/admin/*: For authenticated administrators managing the system.
example.com/api/client/*: For authenticated clients managing their services.
example.com/api/guest/*: Open to anyone, no authentication required, typically for public information.

Schema

All requests are made via POST method.
All data is sent and received as JSON.
Method names are all lowercase with words separated by underscores (e.g., change_password).
Blank fields are included as null instead of being omitted.
All timestamps are returned in ISO 8601 format.

Authentication

Usernames are either admin or client, depending on the API endpoint. The guest entrypoint won’t require authentication, thus no username.
The password is your API key, available in the client profile or in the FOSSBilling admin dashboard.
The API uses cookies to store sessions.
Authentication credentials should be sent via HTTP Basic Authentication headers, base64 encoded.
For example, to access the admin API:
```
Authorization: Basic base64_encode('admin:YOUR_API_KEY')
```
Most HTTP clients (like curl or Postman) handle the encoding automatically.

Example request

# Example curl request to authenticate and call an admin API endpoint
 
curl -X POST "https://example.com/api/admin/staff/create" \
  -H "Authorization: Basic $(echo -n 'admin:YOUR_API_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Testing123+",
    "name": "John Doe",
    "admin_group_id": 1,
    "status": "active"
  }'
 
# Replace YOUR_API_KEY with your actual API key and adjust the payload as needed.

# Example Python request to authenticate and call an admin API endpoint
 
import requests
from requests.auth import HTTPBasicAuth
 
url = "https://example.com/api/admin/staff/create" # /api/{role}/{module}/{endpoint}
api_key = "YOUR_API_KEY"
 
payload = {
  "email": "[email protected]",
  "password": "Testing123+",
  "name": "John Doe",
  "admin_group_id": 1,
  "status": "active"
}
 
auth = HTTPBasicAuth('admin', api_key)
headers = {
  "Content-Type": "application/json"
}
 
response = requests.post(url, json=payload, auth=auth)
print(response.json())
 
# Replace YOUR_API_KEY with your actual API key and adjust the request as needed.

// Example JavaScript request to authenticate and call an admin API endpoint
 
const url = "https://example.com/api/admin/staff/create"; // /api/{role}/{module}/{endpoint}
const apiKey = "YOUR_API_KEY";
 
const payload = {
  email: "[email protected]",
  password: "Testing123+",
  name: "John Doe",
  admin_group_id: 1,
  status: "active"
};
 
const headers = new Headers();
headers.set("Content-Type", "application/json");
headers.set("Authorization", "Basic " + btoa("admin:" + apiKey));
 
fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error("Error:", error));
 
// Replace YOUR_API_KEY with your actual API key and adjust the request as needed.

If you’re new to API development or need help getting started, join our Discord community or post questions in our forums. Happy coding!

The "Custom" Payment Gateway JavaScript API wrapper