Key Validation API

Every Beak product integrates with the Product Manager through one endpoint. The product sends the key the customer entered, and the Product Manager answers with whether it is valid and what it entitles. The endpoint is public — it needs no operator token — because the key itself is the credential.

POST /api/v1/validate/key
Content-Type: application/json

---

Request

Field	Type	Required	Purpose
key	string	Yes	The product key, BEAK-XXXX-XXXX-XXXX-XXXX
product_code	string	Recommended	The product's code. When present, a key issued for a different product is rejected
machine_id	string	Recommended	A stable identifier for the installation. Used for machine binding
activate	boolean	No, default false	When true and the licence is Active, binds the key to machine_id and moves the licence to Activated
report_usage	integer	No	The product's current usage of the licence metric, for example active users. Stored on the licence

{
  "key": "BEAK-2RBB-YKB8-9RRN-SGNT",
  "product_code": "M365LITE",
  "machine_id": "3f1c9a7e-desktop-01",
  "activate": true,
  "report_usage": 412
}

---

Response

Field	Type	Meaning
valid	boolean	Whether the product may run
status	string	Licence status — active, activated, suspended, expired, revoked, draft, pending_renewal
product_code	string	The product the key was issued for
product_name	string	Display name of the product
tenant_name	string	The customer organisation
plan_type	string	trial, basic, professional, or enterprise
features	array of strings	Feature codes the licence grants
metric_type	string	The metric the licence is limited by
metric_limit	integer	The limit on that metric
metric_used	integer	The last reported usage
expires_at	datetime	End of the licence term
days_remaining	integer	Days until expires_at
message	string	Human-readable outcome, populated on failure

{
  "valid": true,
  "status": "activated",
  "product_code": "M365LITE",
  "product_name": "M365Lite",
  "tenant_name": "Demo Company",
  "plan_type": "enterprise",
  "features": ["dashboard", "licenses", "recommendations"],
  "metric_type": "employees",
  "metric_limit": 500,
  "metric_used": 412,
  "expires_at": "2027-03-19T00:00:00Z",
  "days_remaining": 190,
  "message": ""
}

---

Validation Rules

• Key must exist and be active — A revoked key fails regardless of the licence.
• Licence must be live — Active, Activated, and Pending Renewal pass. Draft, Suspended, Expired, and Revoked fail with the status in message.
• Product must match — When product_code is sent, it must equal the code of the product the key was issued for.
• Signature must verify — The key's stored signature is checked against the licence payload, so a key cannot be altered to point at a different tenant, product, or plan.

Every validation is recorded in the audit log with the calling IP address and increments the key's validation count.

---

Integration Guidance

• Validate on start-up and periodically — Products should validate when they launch and re-check on an interval, so a revocation or expiry takes effect without a restart.
• Send product_code always — It is the check that stops a key for one product being used in another.
• Send activate: true once — On first successful validation from a new installation. Later checks should omit it.
• Report usage when it is cheap to compute — report_usage keeps the licence's usage figure current for operators without a separate call.
• Gate features on features — Treat the returned list as the source of truth for what to unlock; do not hard-code entitlements by plan type.

---

Related Pages

• License Keys
• Licenses
• Products