Clavem

Activation

Activation is the step that registers a license key to one specific device, so the licensing server can count how many devices use the key and refuse more once the device limit is reached.

How it works

  1. The customer pastes their key into the app.
  2. The app sends the key, a device name and optionally a fingerprint to the server.
  3. The server checks the license status first. Disabled and expired licenses are refused before the device limit is even looked at.
  4. If a seat is free, the server creates an activation, also called an instance, and returns its id.
  5. The app stores the key, the instance id and the signed token, and turns on the paid features.

The first successful activation also moves a license from inactive to active.

An activation call

This is the shape of Clavem’s call. The values are samples.

curl https://clavem.io/v1/licenses/activate \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "YOUR-LICENSE-KEY",
    "instance_name": "Ada'"'"'s MacBook Pro",
    "fingerprint": "9f2c1e0b7a"
  }'
{
  "activated": true,
  "error": null,
  "license_key": { "status": "active", "activation_limit": 3, "activation_usage": 2, "expires_at": null },
  "instance": { "id": "47596ad9-a811-4ebf-ac8a-03fc7b6d2a17", "name": "Ada's MacBook Pro" },
  "token": "sgt1.eyJ2IjoxLCJsaWQiOjMwNSwi…"
}

Keep instance.id. Every later validate and deactivate call needs it.

What can go wrong

Status error Cause
400 instance_name: Invalid input: expected string, received undefined A parameter is missing. The message starts with its name.
400 This license key has been disabled. The license was revoked or its order refunded.
400 This license key has expired. The expiry date passed or the subscription ended.
400 This license key has reached the activation limit. Every seat is in use and no fingerprint matches an existing one.
404 license_key not found. No such key.
429 Too many requests. Try again in a minute. Rate limit: 120 requests a minute per IP address and 60 per key.
503 A generic message Temporary failure. The response carries Retry-After: 5.

Show the error string to the customer. Branch your own logic on the HTTP status and on activated, not on the text.

Activation versus validation

Activation binds a key to a device and uses a seat. It happens once per device. Validation, POST /v1/licenses/validate, uses no seat. The app calls it at every launch to learn whether the license is still valid, and passes the instance_id so the server can record when the device was last seen. Calling activate at every launch would burn a seat each time unless you send a fingerprint.

How Clavem handles it

The License API needs no secret: the key is the credential, so nothing sensitive ships in your app. Sending a fingerprint makes activation idempotent. Activating again with a fingerprint already active on that license returns the same seat with its name updated. Without one, each call takes a new seat. See machine fingerprint for how to build one, the API reference for every field, and the Swift activation guide for working code. The device limit page explains what the activation_usage counter means.

Questions

Does activation need an internet connection?

With an online license server, yes, once per device. After that the app can keep working offline from a signed token until its re-validation date.

Is activation the same as validation?

No. Activation uses a seat and happens once per device. Validation only asks whether the license is still good and happens at every launch.