Activation API overview¶

This API is used by on-premise products (apps installed by the user) to activate and validate token-based licences. Internal endpoints (top-up, checkout, dashboard) are not covered here.

Base URL & format¶

https://berlanggan.web.id/v1

All requests & responses are JSON.
All activation endpoints use POST and always return HTTP 200 — the outcome is in the status field of the body (activation-API convention).
Money: whole Rupiah; timestamps ISO-8601 UTC.

Interactive docs (OpenAPI) are at /v1/docs.

Authentication¶

The primary credential is the licence key itself (license_key), a "license-key-as-credential" model like Keygen/Cryptlex.

A seller/product may enable an additional product secret. When enabled, include the header:

X-Berlanggan-Secret: <product secret>

If no secret is configured for that product, the header may be omitted. Ask the product's publisher whether the secret is required.

Response fields (activation endpoints)¶

Field	Meaning
`status`	`active`, `grace`, `invalid`, `expired`, `revoked`, `suspended`, `seat_full`, `rate_limited`.
`token`	Signed activation token. Store it; send it back on `validate`.
`expires_at` / `token_expires_at`	When the token must be refreshed (via `validate`).
`license_expires_at`	When the licence/subscription ends (`null` for a perpetual licence).
`grace_days`	How many days the product may keep running offline after the token expires.
`entitlements`	A `key → value` object for local feature gating, e.g. `{"MAX_AGENTS": 10}`.
`entitlement`	The canonical entitlement envelope that is signed.
`entitlement_signature`	Base64 Ed25519 signature over `entitlement`.

The statuses a product may treat as "allowed to run" are active and grace. For anything else the product should limit/disable itself per its own policy.

Possible statuses¶

`status`	Meaning	Product action
`active`	Licence valid.	Run normally.
`grace`	Valid but in a grace window (e.g. an overdue subscription).	Run normally; show a soft warning.
`expired`	The licence period ended.	Lock paid features.
`suspended`	Temporarily suspended (e.g. arrears).	Lock; ask the user to check their account.
`revoked`	Permanently revoked.	Lock.
`seat_full`	All seats in use.	Ask the user to release another device.
`invalid`	Wrong or tampered key/token.	Ask for re-activation.
`rate_limited`	Calling too often.	Back off, retry later.

Endpoints¶

Endpoint	Purpose
`POST /v1/activate`	Register a device, issue a token.
`POST /v1/validate`	Heartbeat — validate & refresh the token.
`POST /v1/deactivate`	Release a device seat.
`POST /v1/operation-authorize`	Short-lived grant for a configured premium operation.
`GET /v1/catalog/products/{slug}/plans`	Public plan list for a product.

Details in Activate, validate & deactivate.

Outbound webhooks¶

Berlanggan can also push license.issued / license.renewed / license.suspended events to a product endpoint (signed with X-Berlanggan-Signature). See Outbound webhooks.