Flaem

API, webhooks, Terraform and CLI: drive Flaem from code

Customers and operators drive Flaem from code: through a public API with scoped keys, 44 signed webhook events, a TypeScript client, Terraform and a command line tool. An AI assistant gets the same permissions over MCP, and WHMCS, Blesta, Paymenter and HostBill run servers through the billing bridge.

  • Your script or app
  • TSTypeScript client
  • Terraform
  • Command line
  • AI assistant over MCP
  • WHMCS, Blesta, Paymenter, HostBill
API key
  • Permission scopes
  • Requests per minute
  • Allowed addresses
  • Usage log entry
Your Flaem installation

Services, nodes, billing and tickets

Your Flaem installation
44 webhook event types
Your systems

Every way into the API passes the same key checks, the AI assistant and the billing system included.

01API keys

An API key that says exactly what it may do

You create a key in the panel and decide right away what it covers, how many requests a minute it may send and from which addresses. Every call it makes lands in a log, and swapping it for a new one does not interrupt the integration.

Scopes

Specific permissions instead of one "everything". There is no scope that covers everything, so a broad key is always visible in the list.

Per-minute limit

120 requests a minute by default. A customer can only lower it, and the operator raises it.

Allowed addresses

You pin a key to up to 25 addresses or subnets. From anywhere else it does not work.

k7m2p9qx4tbn_**********************
prefix shown in the logsecret shown only once

Expiry date

After the date you set, the key stops working on its own.

Rotation with overlap

The new key takes over the traffic and the old one keeps answering until the window you set ends, so a new deployment does not break the integration.

Usage log

Every call with its key, path and result. The public prefix is enough to know which key it was.

The secret is shown once

The full key appears only when it is created. The database stores nothing but its hash.

A notice about new keys

When a new API key or a new webhook appears on an account, the account owner is notified.

02Scopes

Permission scopes for every area

A key gets only the areas the integration needs, separately for reading and for changes. A scope never grants more than the key owner has: a support agent's key with admin read access sees only what that agent's role sees.

AreaScopeWhat it allows
Accountaccount.readThe key owner's profile, roles and referral overview.
Cataloguecatalog.readPackages, games, variants, versions and add-ons for sale.
Servicesresources.readList and details of services, including allocated ports.
Purchaseresources.provisionBuying new services, paid from the wallet balance.
Lifecycleresources.lifecycleCancelling, suspending, unsuspending and resizing services.
Power and consoleresources.powerStart, stop, restart, console commands, reinstall and startup configuration.
Filesresources.files.readresources.files.writeReading directories and files, and with write access creating, changing and deleting files.
Softwareresources.softwareInstalling software on a service and web hosting runtimes.
Metricsmetrics.readCPU, memory, disk and network of a service.
Network and DNSnetwork.readnetwork.writeDNS records, website domains and firewall rules.
Emailmail.readmail.writeMailboxes and aliases on a mail-enabled service.
Billingbilling.readbilling.writeWallet balance and invoices, and with write access starting a wallet top-up.
Collaboratorssubusers.readsubusers.writeOther people's permissions on services and the log of their actions.
Ticketssupport.readsupport.writeReading, opening, replying to and closing tickets.
Notificationsnotifications.readThe key owner's in-panel notifications.
Resellerreseller.readreseller.writeA reseller's customers, their services and invoices, and with write access settings and marked-up packages.
Webhookswebhooks.readwebhooks.writeReceiving addresses, deliveries and replays of events.
Administrationadmin.readadmin.writeInstallation-wide data, plus node and catalogue changes. Only for an owner who holds the admin role.
AI assistantmcp.connectOpens the MCP endpoint and nothing else. Each assistant tool still needs the scope of its own operation.
Billing bridgebilling.bridgeRunning services from a billing system. It cannot be combined with any other scope.
03Documentation

OpenAPI 3.1 documentation and an API changelog in every installation

Every installation publishes its API description in the OpenAPI 3.1 standard and a Developers page with code samples and guides. The description is built from the same route table as the API itself, and a test in the code stops any release where the documentation would drift from reality.

{  "openapi": "3.1.0",  "paths": {    "/api/v1/resources": { "get": { ... } },    "/api/v1/resources/{id}/power": { "post": { ... } }  }}
OpenAPI 3.1
A machine-readable description of every route, to generate a client in any language.
Developers page
Code samples and guides for your customers' developers, inside your panel.
Public, no sign-in
The reference lives at the installation's address, so a developer can read it before creating an account.

API changelog

The operator keeps it in the panel. An entry starts as a draft and has a kind of change, the endpoints it touches and translations into the installation's languages. An entry about a deprecation or a removal is announced once to everyone with an active API key and to the api.change_announced webhook.

Draft entry
Publish
Notify key holders
  • Addedlisted in the changelog
  • Changedlisted in the changelog
  • Deprecatedannounced to key holders
  • Removedannounced to key holders
  • Fixedlisted in the changelog
04TypeScript client

A ready TypeScript client, checked by the compiler

The client is generated from the installation's OpenAPI description. The path, method, parameters and request body are checked at compile time, so a call to an endpoint that does not exist simply does not compile.

1import { createClient } from "@flaem/client";231const flaem = createClient({4  baseUrl: "https://panel.example.com",5  apiKey: process.env.FLAEM_API_KEY!,6});782const services = await flaem.get("/api/v1/resources");93await flaem.post("/api/v1/resources/{id}/power", {10  path: { id: services[0]!["id"] as string },11  body: { action: "restart" },12});
  • No runtime dependencies, ESM with type declarations
  • Node 20 or newer and any browser with fetch
  • One error class with a stable refusal code
  • Paged lists walked in a loop, page by page
  • An AbortSignal on every call
05Webhooks

44 webhook event types, signed and retried

When something happens to a service, a payment, a domain or a ticket, Flaem sends the event to your system's address. Each one is signed, retried when the receiver does not answer, and kept in a delivery log.

Six attempts at growing intervals

A receiver that went away for a moment during a deploy gets the event in one of the first attempts. One that is gone for good stops receiving events before anyone has forgotten what they were about.

  1. Attempt 1no answer
  2. after 30 s
  3. after 2 min
  4. after 5 min
  5. after 15 min
  6. after 1 h

Services

13
  • resource.provisioned
  • resource.provisioning_failed
  • resource.app_installed
  • resource.app_install_failed
  • resource.cancelled
  • resource.cancel_incomplete
  • resource.force_cancelled
  • resource.suspended
  • resource.unsuspended
  • resource.suspension_warned
  • resource.suspension_warning_withdrawn
  • resource.deletion_eligible
  • resource.deletion_scheduled

Payments and billing

15
  • billing.payment_received
  • billing.purchase_declined
  • billing.order_undeliverable
  • billing.refund_issued
  • billing.resource_renewed
  • billing.renewal_due_soon
  • billing.renewal_past_due
  • billing.trial_ends_soon
  • billing.payment_method_declined
  • billing.payment_method_disabled
  • billing.payment_method_expiring
  • billing.community_funding_short
  • billing.reseller_sale_settled
  • billing.reseller_margin_returned
  • billing.reseller_margin_shortfall

Domains

13
  • domain.registered
  • domain.transferred
  • domain.renewed
  • domain.expires_soon
  • domain.expired
  • domain.redemption
  • domain.released
  • domain.registration_failed
  • domain.dnssec_enabled
  • domain.dnssec_disabled
  • domain.dnssec_rolled
  • domain.host_changed
  • domain.host_removed

Tickets and API

3
  • support.ticket_answered
  • support.ticket_closed
  • api.change_announced
HMAC-SHA256 signature
The signature covers the timestamp and the body, so the receiver can spot a forgery and an old event sent a second time.
Disabled with a reason
After 20 failed deliveries in a row the address is switched off with the reason given, instead of quietly piling up a queue.
Protecting your network
A webhook never goes to an internal address and never follows a redirect, so nobody can use it to look inside your network.
Test event and log
One button sends a test event, and the log shows every attempt with its response code.
06AI assistant

An AI assistant in your installation over MCP, with 23 tools

The operator connects Claude or any other MCP-compatible assistant to their own installation and asks it about nodes, services, customers, invoices, tickets, alerts and abuse. The assistant can do exactly what its key can, and every call goes to the audit log.

Example question

Which nodes are in trouble and whose services are on them?

  1. list_alerts
  2. list_nodes
  3. get_node_usage
  4. list_services

Each tool is an ordinary API request made with the assistant's key, with the same scope, limit and log entry.

Read

18
  • get_platform_overview
  • list_nodes
  • get_node
  • get_node_usage
  • get_node_transfer
  • list_services
  • get_service
  • get_service_transfer
  • list_customers
  • get_customer
  • list_invoices
  • get_invoice
  • list_tickets
  • get_ticket
  • list_alerts
  • list_escalations
  • list_abuse_cases
  • get_abuse_case

Change

5
  • power_service
  • suspend_service
  • unsuspend_service
  • reply_to_ticket
  • acknowledge_alert

What the assistant will not do

  • Delete or reinstall anything
  • Cancel a service or move money
  • Change a node or any credentials
Flaem operator dashboard: sales and MRR, live nodes and the issues waiting for a person
Any client
Claude Code, Claude Desktop or any MCP client that connects over HTTP with a custom header.
Content is data, not orders
Tickets and complaints reach the assistant word for word. For summarising, you give it a key without write scopes.
Cut off with one click
A revoked key stops working on the assistant's next request.
07Terraform and CLI

Terraform and a command line tool for your customers

Customers who keep their infrastructure in code describe their services in Terraform files and handle daily operations from a terminal and from scripts. Both tools run on the same API keys, so the same scopes, limits and log apply.

A file describing services

The customer's services written down in Terraform configuration, in a repository next to the rest of their infrastructure.

2

terraform plan

Before a change, the customer sees what will be created, changed and removed.

3

terraform apply

The change goes through the Flaem API, with the customer's key and scopes.

Command line

Service operations from a terminal and from scripts, on the same API key as the rest of the integration. The same limit, the same allowed addresses and the same usage log.

08Billing bridge

The billing bridge: your billing system counts the money, Flaem runs the servers

If you stay with WHMCS, Blesta, Paymenter or HostBill, the Flaem module connects it to the panel. The billing system stays the owner of the customer, the money, the term and the dunning, while Flaem creates, suspends and changes the servers.

WHMCSBlestaPaymenterHostBill

Your billing system

  • The customer and their details
  • Payments and invoices
  • Service term and renewals
  • Dunning and the decision to suspend

Flaem

  • The server, its resources and its node
  • The customer's service panel
  • Suspension when the billing system asks for it
  • Disk and transfer usage sent back
Action in the billing systemWhat Flaem does
CreateLinks the customer to a panel account, opening one from their email address the first time, and builds the service.
Suspend and unsuspendSuspends the service for non-payment and reinstates it after payment.
TerminateEnds the service and opens a data download window, unless the product says otherwise.
Change packageMoves the service to the new package with the chosen options.
Log in to panelMints a one-time sign-in link at the moment of the click, for the customer and for the admin.
Service tabShows the service state, package and usage, read live.
Usage updateWrites disk and transfer to the service, and skips it when there is no sample instead of writing zero.
Change on the Flaem sideA suspension, reinstatement or cancellation in the panel flows back to the billing system.

No second server by mistake

Every change carries a key built from the service number and the operation, so a job retried after a timeout never builds a second machine.

The panel does not invoice them

A bridged service gets no invoices, renewals or non-payment suspensions in Flaem. Your system handles that.

A separate key with its own limit

The bridge key holds a single scope the regular API does not accept, and a default limit of 600 requests a minute.

WHMCS module with every release

One zip archive with its SHA-256 sum, published with each Flaem release. No Composer and no Marketplace install.

The billing bridge to WHMCS: option combinations mapped to plans, service states and the latest bridge calls
09Questions

Questions about the API, webhooks and integrations

Limits, documentation, the AI assistant and working with the billing system you already have.

No. They create an API key in their own panel, on their own account, with the scopes and limit they choose.

120 by default. A customer can only lower that limit, and the operator raises it. A billing bridge key has 600 by default.

In every installation, publicly: a reference page and an OpenAPI 3.1 file at the operator's panel address, plus a Developers page with samples and guides.

No. Its tools do not delete, reinstall, cancel, move money, touch nodes or credentials. The only changes it can make are powering a service, suspending and reinstating it, replying to a ticket and acknowledging an alert, and only with the right scopes.

Flaem retries a delivery up to 6 times, at intervals from 30 seconds to an hour. After 20 failed deliveries in a row it switches the address off and gives the reason.

Yes. The billing bridge module leaves billing to WHMCS while Flaem handles the servers. If you decide to move over completely, the importer brings over customers, balances and services.

Yes, up to three attempts by default. Always when refused for rate limiting, and on server errors only for methods that are safe to repeat. It never repeats a write that may already have happened.

We will show the API on your integration

Tell us what you connect to your panel today: billing, scripts, monitoring or an AI assistant. In the demo we show keys, webhooks and the bridge on your own example.