Babel Licensing API Reference

The Babel Licensing Service exposes a REST API to manage licenses, products, customers, orders, releases and the rest of the licensing data, to run the licensing operations of protected applications, and to serve application updates. This page covers what every endpoint has in common. The pages linked at the bottom list the endpoints one by one.

Base URL and Versioning

Every route starts with the version segment /v1:

https://your-licensing-server/v1/...

The host and port come from the Kestrel section of the service appsettings.json; the default configuration listens on https://localhost:5000 (see Kestrel). The code samples in this reference show paths only, so prepend your server address.

The REST API is served only when Application:EnableWebApi is true, the default. With Application:EnableSwagger also enabled, the service publishes the OpenAPI document this reference is generated from at /swagger/v1/swagger.json, and Swagger UI at /swagger.

Content Types

• Request and response bodies are JSON (application/json) with camelCase property names.
• Dates are UTC strings such as 2026-09-01T00:00:00.000Z.
• Enumerations are serialized as numbers, unless Application:SerializeJSonEnumAsString is enabled.
• Properties with a null value are left out of responses while Application:IgnoreJSonDefaultValues is true, as it is in the default configuration.
• A client that sends Accept: application/toon receives TOON instead of JSON. Without that header the response is JSON.
• Uploading a release artifact uses multipart/form-data, and the update feed files are text/yaml. See Product Releases and Updates.

Authentication

The API accepts two credentials. Which one an endpoint takes is shown under each endpoint as Authentication.

The header name x-api-key can be changed with Application:ApiKeyHeaderName.

API keys

An API key belongs to a user, its owner. A request authenticated by the key acts with the roles of that owner, and the key adds its own permission bits on top:

The permission follows the HTTP method, not what the route does: POST /v1/products/{productId}/releases/{releaseId}/downloads/verify changes nothing but still needs Create. Permission bits are checked on the Management API, release download and webhook routes. A key without the bit for the method receives 403.

A key is refused with 401 when it is unknown, revoked or past its expiration date. When a key has no owner it carries no role, so every role-protected route answers 403, and POST /v1/api-keys refuses to create one. When the service creates the administrator account at startup (Application:AdminUsername and Application:AdminPassword), it also creates an API key with all permissions for that user.

The service caches a validated key for Application:ApiKeyCacheDuration (3 minutes in the default appsettings.json). A change to a key, such as revoking it or removing a permission, can take that long to apply.

curl https://your-licensing-server/v1/products?take=10 \
  -H 'x-api-key: api_xxxxxxxxxxxxxxxxxxxxxxxx'

{
  "success": true,
  "user": "admin",
  "roles": [ "Administrator" ],
  "permissions": 1,
  "keyName": "read-only"
}

Bearer tokens

POST /v1/auth/login returns a JWT in token and its lifetime in seconds in expiresIn (Application:TokenExpiration, 30 minutes by default). Send it as Authorization: Bearer <token>.

curl -X POST https://your-licensing-server/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<password>"}'

curl -X POST https://your-licensing-server/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"password":"AAAAA-BBBBB-CCCCC-DDDDD"}'

GET /v1/auth/user returns the signed-in user with its roles, settings and active API keys. GET /v1/auth/session works with both credentials: with a bearer token it reports the user and roles, and permissions is absent.

Roles and Access

The service defines the roles Administrator, LicenseManager and Sales, and every Management API route requires one of them. The roles Customer and Application also exist, but no REST route requires them.

A request with a valid credential but without the role answers 403.

Anonymous Endpoints

These routes take no credential:

• POST /v1/auth/login.
• The update feed: GET /v1/updates/{productCode}, the electron-updater feed files and the artifact download. A caller identifies its license, when it has one, with the X-Babel-User-Key header or the userKey query parameter. See Updates.
• GET /v1/extensions/keys, the public keys that sign the feed.
• The health check at /health (Application:HealthCheckEndPoint), when Application:EnableHealthCheck is true. It is not part of the OpenAPI document; see Health Check.

The licensing operations under /v1/license are not anonymous. An application that has only its user key signs in with it first, as shown in Bearer tokens.

Querying Lists

Most GET routes that return a list accept the same query parameters:

With skip or take and no sort, results are ordered by primary key, so pages stay stable. The response carries the page of items and a total count of the items that match filter, such as totalProductsCount. Each endpoint page lists the parameters that route accepts: the release download list, for example, has no select, and the token lists add countOnly.

URL-encode the values. curl -G with --data-urlencode does it for you:

# Products whose code starts with "babel", newest first, three properties only
curl -G https://your-licensing-server/v1/products \
  -H 'x-api-key: <key>' \
  --data-urlencode 'filter=code.StartsWith("babel")' \
  --data-urlencode 'select=id,code,name' \
  --data-urlencode 'sort=-id' \
  --data-urlencode 'take=10'
 
# The license with a given user key
curl -G https://your-licensing-server/v1/licenses \
  -H 'x-api-key: <key>' \
  --data-urlencode 'filter=userKey="AAAAA-BBBBB-CCCCC-DDDDD"'
 
# A customer with its contacts
curl -G https://your-licensing-server/v1/customers \
  -H 'x-api-key: <key>' \
  --data-urlencode 'filter=id=42' \
  --data-urlencode 'include=Contacts'

A filter that names an unknown property is not a validation error: the service answers 500 with the parser message, for example No property or field 'nope' exists in type 'Product'.

Updating Resources

PUT requests perform partial updates: a field omitted from the request body keeps its stored value. A value you send explicitly, including false or 0, is applied. Send only the fields you want to change.

This applies to licenses, license templates, customers, contacts, products, product releases, order products, API keys and webhook events.

When a product release is created without requiresMaintenance, it defaults to true, so the release is available only to licenses in maintenance. For an application product the service refuses requiresMaintenance: false unless Updates:AllowPublicApplicationReleases is enabled. See Releases.

Errors

Error responses come in three shapes.

Service errors

Every route except the anonymous update routes reports errors with a small JSON body:

{ "success": false, "code": 400, "message": "Product 999 not found." }

code repeats the HTTP status. The status depends on the error:

• 400 for a request the client can correct, such as a missing or invalid field. Many “not found” cases on the Management API also answer 400, with the reason in message.
• 401 for a failed login (Invalid username or password., Invalid user key.).
• 500 for anything else, including a failed database operation.
• 520 plus the gRPC status code for the licensing errors shared with the gRPC services. The body message names the error. See Error Codes.

Validation problems

Validation problems use the standard ASP.NET Core application/problem+json body. You get one when the request body cannot be read, for example malformed JSON:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "": [ "Unexpected end while parsing unquoted property name. Path '', line 1, position 4." ] }
}

Update route errors

The update routes use the { success, code, message } body too, but with ordinary HTTP statuses only: 400 for an unknown platform, channel or version, 403 for a revoked or expired license or a refused download, 404 for an unknown product or artifact. They never answer 52x.

Status codes

Rate Limiting

The IpFiltering section of appsettings.json protects the service. The defaults are:

The default excluded paths are the floating license routes (/v1/license/request, /v1/license/release, /v1/license/heartbeat and their gRPC counterparts) and login (/v1/auth/login and the gRPC Authenticate). An application that went over the limit elsewhere can still hold and release its floating seats.

A blocked client receives 429 Too Many Requests with a Retry-After header in seconds and the text body Too many requests. Retry after N seconds. Wait at least that long before retrying. A blacklisted IP (Blacklist) always receives 403.

Login protection is separate. After MaxFailedAttempts failed logins, further logins from that IP fail until the block expires, even with the right password. The update routes count unknown, revoked or expired user keys as failed attempts too, and enough of them block logins from that IP in the same way. See IP Filtering for the configuration reference.

Webhooks

The service can call your endpoints when licenses, orders and reports change. Subscriptions are managed with the Webhooks API and require an API key of an Administrator or LicenseManager. For the event types and payloads, see Supported Events and Webhook Payload Reference. Every delivery is signed with HMAC-SHA256 in the X-Babel-Signature header; see Securing Webhooks for how to verify it.

API Sections