API reference

Contours and rate limits#

Limits are fixed-window per IP. A rejected request answers 429 with the standard headers:

HTTP/1.1 429 Too Many RequestsRetry-After: 60RateLimit-Limit: 20RateLimit-Remaining: 0RateLimit-Reset: 60

Authorization model#

Panel: session cookie#

POST /api/v1/panel/auth/login sets the certified.auth cookie (HttpOnly, SameSite=Lax, sliding 7 days). When the account has TOTP enabled the response carries a short-lived ticket instead — the session only opens after POST /auth/login/2fa.

Panel: personal access token (Bearer)#

For machine integrations you can present a personal access token instead of a cookie: Authorization: Bearer cfed_pat_…. The token format is cfed_pat_ followed by base64url of 32 random bytes; the database stores only the SHA-256 hash and a short non-secret lookup prefix.

• A token is bound to a company and acts with Admin authority inside that subtree — it never grants global operator rights.
• A revoked (revokedAt) or expired (expiresAt) token is rejected.
• The secret is shown once, at creation; afterwards only metadata is available.

Client: HMAC signature#

Client endpoints are public. activate uses the license key itself as the shared secret. heartbeat and deactivate require a signed request:

X-CertifiEd-Timestamp: <unix_seconds>X-CertifiEd-Signature: v1=<hex( HMAC_SHA256(key = licenseKey, msg = timestamp) )>

A timestamp outside the ±5 minute window is rejected — that is the replay protection. The scheme is implemented by HmacRequestValidator; the SDK signs requests for you.

Error format#

One JSON shape across every endpoint of both contours:

{  "code": "license.company_not_active",  "message": "Company is Archived.",  "status": 400}

Panel · Auth#

• login — req { email, password } → LoginResponse { twoFactorRequired, ticket, user }. When twoFactorRequired is true, user is null and no cookie is issued.
• login/2fa — req { ticket, code } → AuthUserResponse { id, email, displayName, isOperator }. code is a live TOTP or an unused recovery code; the ticket lives 5 minutes.
• invite/{token} — InvitePreviewResponse { email, companyName, role, expiresAt }. accept-invite — req { token, password }; the password needs 8+ characters and the invite token lives 7 days.
• forgot-password — req { email }, always 204: address existence is never disclosed. reset-password — req { token, newPassword }; change-password — req { currentPassword, newPassword }.
• 2fa/enroll → { secret, otpauthUri } (base32 secret and the QR URI). 2fa/enable — req { code } → { recoveryCodes[] }, shown once. 2fa/disable — req { password, code }.

Panel · Companies#

• create — req { name, slug, parentId?, contactEmail? }. A slug is 1–64 characters of [a-z0-9-], must not start or end with a hyphen, and is unique among siblings. parentId: null creates a root company — operators only.
• reparent — req { newParentId } (null moves the node to the root) → CompanyResponse. Rebuilds the ltree path and depth for the node and every descendant in one transaction.
• CompanyResponse { id, name, slug, parentId, path, depth, status, contactEmail, createdAt }.

Panel · Templates#

• create template — req { name, productCode, description?, defaultOfflineDays, defaultValidityDays }. productCode is unique; defaultOfflineDays is clamped to 1..30.
• create version — req { configSchema, defaults?, changelog? }; configSchema and defaults are JSON strings. The version immediately becomes currentVersionId.
• LicenseTemplateResponse { id, name, productCode, description, defaultOfflineDays, defaultValidityDays, status, currentVersionId, createdAt }.
• TemplateVersionResponse { id, templateId, version, configSchema, defaults, signingKeyId, changelog, createdAt }.
• SigningKeyResponse { id, status, notBefore, notAfter, createdAt, publicKeyHex }.

Panel · Licenses#

Search#

GET / — query companyId?, templateId?, status? (Active / Revoked / Expired …), search?, page=1, pageSize=50 (max 200) → PagedResult<LicenseResponse> { items, total, page, pageSize }. An unknown status yields license.invalid_status (400); a company outside your scope yields auth.company_out_of_scope (403).

Issuing#

{  "companyId": "019f7ef0-0ca2-73b1-8830-f016df1bb6d0",  "templateId": "019f7ef0-0d1c-7207-9c20-21d14619ed4a",  "config": "{\"features\":[\"export\"],\"limits\":{\"maxSeats\":25}}",  "expiresAt": null,  "offlineDays": 7,  "isTrial": false,  "hwBinding": "none",  "hwFingerprint": null}

• config is a JSON string (features / limits) embedded into the signed token.
• expiresAt: null → now + template.defaultValidityDays, and with isTrial: true → now + Licensing:DefaultTrialDays (14 days by default).
• offlineDays is clamped to 1..Licensing:MaxOfflineDays (30 by default).
• hwBinding is none / fixed / firstActivation — see Hardware binding. When the field is omitted the mode is inferred from hwFingerprint: present → fixed, absent → none.
• Response LicenseIssueResponse { id, licenseKey, token, publicKey }, publicKey in hex.

Bulk issuance#

POST /bulk — req { templateId, items: [{ companyId, config? }], config?, expiresAt?, offlineDays?, hwFingerprint?, isTrial?, hwBinding? }. An item-level config overrides the batch-wide one; the remaining fields apply to every item. At most 200 items (license.bulk_too_large); an empty list yields license.bulk_empty.

A failing item (missing rights, archived company, malformed config) does not abort the batch — the error is reported in that item's row. Successful licenses are persisted in a single transaction.

{  "requested": 2,  "succeeded": 2,  "failed": 0,  "results": [    {      "companyId": "019f7ef0-0ca2-73b1-8830-f016df1bb6d0",      "licenseId": "019f7ef0-48f7-7e69-afda-dbe061cd6da8",      "licenseKey": "CFED-N2XH-SMPJ-VCF2-G2GB",      "errorCode": null,      "errorMessage": null    },    {      "companyId": "019f7ef0-0ce1-708d-9621-f89c477b7faf",      "licenseId": "019f7ef0-48fc-74f7-9bd9-cf15478c5ae4",      "licenseKey": "CFED-RY8S-S4F8-Y9ZJ-UDBZ",      "errorCode": null,      "errorMessage": null    }  ]}

Transfer#

POST /{id}/transfer — req { newCompanyId } → LicenseTransferResponse { licenseId, licenseKey, companyId, currentVersion, token, publicKey, deactivatedActivations }.

The licensee (sub) is baked into the signed token, so a transfer signs a new license version (same license key, currentVersion + 1, config preserved) and deactivates every active activation, freeing their seats. The customer must download the `.ced` again. Requires Admin on both the source and the target company.

Hardware rebinding#

POST /{id}/rebind — req { hwFingerprint, reason?, hwBinding? } → LicenseResponse.

• hwFingerprint: "<new fingerprint>" pins the license to the new machine (the mode becomes fixed).
• hwFingerprint: null releases the binding: fixed falls back to firstActivation (it re-pins on the next activation), none stays none.
• hwBinding forces the resulting mode instead of the inferred one.

Every active activation is deactivated and the license is re-signed as a new version — the customer must download the .ced again. Requires Admin on the license's company (operators always qualify). Webhook event — license.rebound. Details in Hardware binding.

Everything else, and the models#

• reset activation — POST /{id}/activations/{activationId}/reset → 204. Deactivates a single activation, freeing its seat (floating seats). Idempotent; an activation belonging to another license yields activation.not_found (404).
• download — the .ced body: { licenseKey, token, publicKey }; file name {licenseKey}.ced.
• public-key — LicensePublicKeyResponse { publicKey } (hex).
• LicenseResponse { id, licenseKey, companyId, templateId, status, config, offlineDays, currentVersion, expiresAt, issuedAt, activatedAt, lastHeartbeatAt, revokedAt, revocationReason, isTrial, hwBinding, hwFingerprint }.
• ActivationResponse { id, hwFingerprint, machineName, status, activatedAt, lastHeartbeatAt, deactivatedAt }.
• HeartbeatRecordResponse { id, activationId, occurredAt }.

Panel · Users#

• invite — req { email, companyId, role, displayName? }; role is one of owner / admin / viewer. Creates a pending account and emails an /accept-invite?token=… link that lives 7 days.
• UserResponse { id, email, displayName, isOperator, totpEnabled, status, companyId, role, lastLoginAt, createdAt }; status is pending / active / revoked.

Panel · Operator#

The whole group is operator-only — anyone else receives auth.operator_required (403).

• overview — OperatorOverviewResponse { totalCompanies, rootCompanies, licenses { active, suspended, revoked, expired, total }, trialLicenses, activeActivations, licensesExpiringIn30Days, templates, signingKeys { … }, webhookEndpoints, deliveryHealthLast24h { pending, failed, success } }.
• tenants — OperatorTenantResponse { id, name, slug, status, contactEmail, descendantCount, licenseCount, createdAt }.
• licenses — OperatorLicenseResponse { id, licenseKey, companyId, companyName, templateId, productCode, status, isTrial, issuedAt, expiresAt, activatedAt, revokedAt }.
• users — OperatorUserResponse { id, email, displayName, status, totpEnabled, lastLoginAt, createdAt }; status is pending / active / revoked.
• users/invite — req { email, displayName? } → OperatorUserResponse with status: "pending". If the user already exists and is active you get user.already_exists (409): promote them instead of inviting.

Panel · Analytics#

• Scope: an operator without companyId sees the whole platform; everyone else sees the union of their visible subtrees. A companyId narrows results to that company's subtree (requires Viewer on it).
• usage — query from?, to?, companyId?. The default window is the last 30 days, the maximum is 366 days (analytics.range_too_large; from > to yields analytics.invalid_range).
• distribution — query companyId? → { licensesByTemplate[], activationsByTemplate[], topCompaniesByActivations[] }; the first two are { templateId, productCode, templateName, count }, the third is { companyId, companyName, count } (top 10).

{  "from": "2026-06-20T09:53:33.90+00:00",  "to": "2026-07-20T09:53:33.90+00:00",  "activations":    [ { "date": "2026-07-20", "count": 3 } ],  "heartbeats":     [],  "licensesIssued": [ { "date": "2026-07-20", "count": 4 } ]}

Panel · Webhooks#

• create — req { url, secret, description, events[] }. url is an absolute URI; secret is at least 16 characters (it is the HMAC key for deliveries); events come from event-types.
• update — req { url?, secret?, description?, isActive?, events? }.
• WebhookEndpointResponse { id, url, description, isActive, events, lastDeliveryAt, createdAt }.
• WebhookDeliveryResponse { id, endpointId, eventType, payload, status, attemptCount, responseStatusCode, responseBody, lastError, nextAttemptAt, lastAttemptAt, createdAt }.
• The event catalogue (GET /event-types): license.issued, license.revoked, license.expired, license.activated, license.deactivated, license.heartbeat_missed, license.transferred, `license.rebound`.

The delivery format and signature verification live in the Webhooks section.

Panel · API tokens#

• create — req { name, companyId, expiresInDays? } (1..3650) → CreatedApiTokenResponse { token, secret }. The `secret` is shown once; the database keeps only the SHA-256 hash and a non-secret prefix.
• ApiTokenResponse { id, name, companyId, prefix, createdAt, lastUsedAt, expiresAt, revokedAt }.
• Codes: api_token.name_required, api_token.invalid_expiry (400); api_token.not_found (404).

Panel · Audit#

• GET / — query action?, actorEmail?, entityType?, entityId?, from?, until?, limit=100 (max 500), offset=0.
• GET /export — the same filters minus limit / offset, plus format=csv|json (csv by default). The response is streamed as an attachment, Content-Disposition: attachment; filename="audit-YYYYMMDD.csv", with no pagination. CSV uses the header timestamp,actor,action,entityType,entityId,meta and RFC 4180 escaping. An unknown format yields audit.invalid_format (400).
• The export itself is recorded in the log as the audit.exported action.
• AuditLogResponse { id, action, actorEmail, entityType, entityId, meta, ipAddress, occurredAt }.

Client API#

• activate — req { licenseKey, hwFingerprint?, machineName? } → ActivateResponse { activationId, heartbeatToken, heartbeatIntervalSeconds, maxOfflineDays }. Re-activating from the same machine (the same hwFingerprint) reuses the existing activation and does not consume a second seat.
• heartbeat — req { licenseKey, activationId } plus the HMAC headers → HeartbeatResponse { heartbeatToken } (a fresh signed offline marker).
• deactivate — req { licenseKey, activationId } plus the HMAC headers → 204. Frees the seat (floating seats) — the SDK does this in DisposeAsync. Idempotent.
• public-key — ClientPublicKeyResponse { publicKey } (hex).

The heartbeatToken returned by activate / heartbeat is the offline marker shaped as base64url(payload).base64url(signature) — see the License protocol. The SDK caches it as <license>.ced.hb.

Hardware binding and seats#

Activation checks two independent things. The first is the binding mode license.hwBinding:

Codes: activation.fingerprint_mismatch (400, wrong machine), activation.fingerprint_required (400, firstActivation with no fingerprint), activation.not_bound (409, a fixed license whose fingerprint was released — it awaits a rebind). Details in Hardware binding.

The second is the seat limit limits.maxSeats inside the signed config. A positive integer caps the number of active activations; a missing field, zero or a non-numeric value means no limit. Only a brand-new activation consumes a seat — re-activating the same fingerprint does not. Seats are freed by deactivate (client), an activation reset, transfer and rebind (panel).