Authentication
API requests are authenticated using a license key passed in the request body. No Authorization header is required.
License keys are generated automatically when a subscription is created. Each key follows the format LIC-XXXX-XXXX-XXXX-XXXX and is bound to a specific instance upon first validation.
Base URL
The Bleep API is hosted on the web application. All endpoints are relative to this base:
https://<your-bleep-domain>/api/v1The endpoint apps are pre-configured with the correct API URL. You only need to provide your license key.
License Validation
/api/v1/license/validateValidates a license key and binds it to the requesting instance. Called on first launch and periodically (default: every 1 hour). On first call, the license is permanently bound to the instance. Subsequent calls from a different instance will return an instance conflict unless rebind is set to true.
Request Body
{
"license_key": "LIC-A3F2-9B4C-D1E8-7F6A",
"instance_id": "unique-instance-identifier",
"product_version": "1.0.0",
"current_seats": 5,
"server_info": {
"hostname": "office-server",
"os": "windows",
"os_version": "11"
},
"rebind": false
}Required Fields
license_key- Your license key (format: LIC-XXXX-XXXX-XXXX-XXXX)instance_id- Unique identifier for this Bleep instance
Optional Fields
product_version- Current app versioncurrent_seats- Number of active seats on this instanceserver_info- JSON object with hostname, IP, OS detailsrebind- Set to true to transfer the license to a new instance
Success Response (200)
{
"valid": true,
"license": {
"id": "uuid",
"company_name": "Acme Corp",
"plan": "team",
"max_seats": 50,
"current_seats": 12,
"features": ["custom_patterns", "audit_logs"],
"issued_at": "2026-01-20T00:00:00Z",
"expires_at": "2027-01-20T00:00:00Z"
},
"next_check_hours": 1
}Instance Conflict Response (200)
Returned when the license is already bound to a different instance and rebind is false:
{
"valid": true,
"instance_conflict": true,
"message": "This license is already bound to another server.",
"bound_server_info": { "hostname": "old-server" },
"bound_at": "2026-01-20T00:00:00Z",
"license": { ... }
}Error Responses
// 400 - Missing required fields
{
"valid": false,
"error": "invalid_request",
"message": "license_key and instance_id are required"
}
// License not found / expired / revoked / suspended
{
"valid": false,
"error": "license_not_found | license_expired | license_revoked | license_suspended",
"message": "Human-readable error message"
}Heartbeat
/api/v1/license/heartbeatSent periodically by the Bleep app to report status. Updates the activation record and confirms the license is still valid.
Request Body
{
"license_key": "LIC-A3F2-9B4C-D1E8-7F6A",
"instance_id": "unique-instance-identifier",
"active_seats": 5,
"violations_24h": 3,
"version": "1.0.0"
}Required Fields
license_key- Your license keyinstance_id- Instance identifier (same as used in validation)
Optional Fields
active_seats- Number of active seatsviolations_24h- Violations detected in the last 24 hoursversion- Current app version
Response (200)
{
"ok": true,
"license_valid": true,
"messages": []
}When license_valid is false, the license has expired or been revoked since the last check.
Device Sync
/api/device/syncCalled periodically by endpoint apps to sync configuration, policies, and commands from the admin server. The response includes a license_valid field. When false, the endpoint must stop its proxy and restore system settings.
Response includes
{
"mode": "warning",
"policies": [...],
"commands": [...],
"license_valid": true
}When license_valid is false, the endpoint app stops the proxy, clears system proxy settings, and prevents manual restart until the license is restored.
License-Gated Endpoints
The following admin server endpoints return 403 with {"error": "license_expired"} when the server license has expired:
- •
POST /api/seats- Create new device seat - •
POST /api/seats/bulk- Bulk create seats - •
POST /api/seats/<id>/regenerate- Regenerate seat certificate - •
POST /api/enrollment-token- Create enrollment token - •
POST /api/device/enroll- Enroll a new device
Account Deletion
/api/user/deletePermanently deletes the authenticated user's account. Requires an active session (cookie-based auth).
What happens on deletion
- 1. All active and past-due Stripe subscriptions are cancelled
- 2. All active licenses are revoked
- 3. Auth user is deleted
- 4. Customer record is deleted (CASCADE removes subscriptions, licenses, SSO providers)
Response
// Success
{ "success": true }
// Error
{ "error": "Failed to delete account" }CORS & Logging
Both endpoints support CORS preflight requests via OPTIONS:
All API calls are logged including request/response details, client IP, user agent, and response latency.