What each field is for
instance_name is what the player sees on their device page, up to 120 characters. fingerprint is for the server, up to 200 characters, and optional. Send a hash. Activating again with a fingerprint that is already active on the license returns that seat, with its name updated, instead of taking another.
Godot gives you one candidate, OS.get_unique_id(). Its docs attach three warnings. The string may change without notice if the player reinstalls or upgrades the OS or changes hardware. Outside programs can falsify it. And on Web it returns an empty string and generates an error. So it is a convenience for not wasting seats, and never a security measure.
Methods to add to the license autoload
These go in license.gd from the validation page and reuse its _post, _save, _load and _clear.
func fingerprint() -> String:
if OS.has_feature("web"):
return "" # get_unique_id() is empty on Web and logs an error
var id := OS.get_unique_id()
if id.is_empty():
return ""
return ("inkwell|" + id).sha256_text() # your own salt; send a hash, never the raw id
func default_device_name() -> String:
var model := OS.get_model_name() # real on Android, iOS, macOS and Windows; "GenericDevice" elsewhere
return OS.get_name() if model == "GenericDevice" else "%s (%s)" % [OS.get_name(), model]
## Returns "" on success, otherwise a sentence for the player.
func activate(license_key: String, device_name: String = "") -> String:
var body := {
"license_key": license_key.strip_edges(),
"instance_name": device_name if device_name != "" else default_device_name(),
}
var fp := fingerprint()
if fp != "":
body["fingerprint"] = fp
var r := await _post("activate", body)
if r.status == 200 and r.body.get("activated", false) == true:
_save({"key": body["license_key"], "instance": r.body.instance.id, "token": r.body.token})
_set_state(State.LICENSED)
return ""
if r.status == 400:
var lk = r.body.get("license_key")
# Expired and disabled licenses also answer 400 with this block, so check the status first.
if lk is Dictionary and lk.get("status") == "active" and lk.get("activation_limit") != null \
and lk.get("activation_usage") == lk.get("activation_limit"):
return "This license is already used on %d of %d devices. Remove one at clavem.io/licenses/manage, then try again." \
% [int(lk.activation_usage), int(lk.activation_limit)]
return str(r.body.get("error", "Activation failed."))
if r.status == 404:
return "That key was not found. Check it for typos."
return "Could not reach the license server. Try again in a minute."
## Returns true when the seat is free, or was already gone.
func deactivate() -> bool:
var saved := _load()
if saved.is_empty():
return true
var r := await _post("deactivate", {"license_key": saved.key, "instance_id": saved.instance})
if r.status == 200 or r.status == 404:
_clear()
_set_state(State.UNLICENSED)
return true
return false # no answer: keep the instance id so the player can try again
Wire activate to a button: var message: String = await License.activate(key_edit.text, name_edit.text), and show message when it is not empty. Pre-fill name_edit with default_device_name(). On desktop Godot does not know the computer’s name, so an editable field is how a player ends up with Ada's gaming PC on the device page instead of Windows.
A fingerprint that drifts
Validation sends license_key and instance_id. The fingerprint goes only to activate. Two consequences:
- An installed game keeps working when
get_unique_id()changes after an OS upgrade. The stored instance id still names the seat. - A fresh activation takes a new seat when the id changed and the player lost
user://license.json: an OS reinstall does both. The old seat stays used until the player removes it on the device page, where they enter their key and see each device by name.
The limit-reached screen
A full license answers 400 with This license key has reached the activation limit. and a license_key block with activation_limit and activation_usage. The code above shows both numbers. Expired and disabled licenses also answer 400 with the same block, which is why it tests status first and otherwise shows the server’s error.
JSON.parse_string returns numbers as floats, hence the int(...) in the message. activation_limit is null for an unlimited license, and the != null test covers that.
Edge cases that belong to Godot
- Never activate from the editor.
License._ready()already treatsOS.has_feature("editor")as licensed. Test activation in an exported build, so your development machines do not take seats. - Web exports. There is no fingerprint. Without one, every activation takes a seat, and a browser that clears storage orphans the old one. For a Web build, consider validating with the key alone and no
instance_id, and accept that no device limit applies there. - Dedicated servers and CI runners. Do not activate them. Use
OS.has_feature("dedicated_server")in an exported server, and keep activation out of test pipelines. - Renamed projects.
user://includes the project name, so a rename loses the stored instance id for every player. See the note on the validation page. - Do not deactivate on quit. Godot’s
NOTIFICATION_WM_CLOSE_REQUESTis not guaranteed on a crash or kill, and a coroutine started while quitting may not finish. Deactivate from an explicit “Move this license” button only.
Doing this with Clavem
Each product has a default device limit, and players manage seats on their own device page, no account needed. See device limits and the activate endpoint for every field and error.
Questions
What happens if OS.get_unique_id() changes after an update?
Validation sends the stored instance id, not the fingerprint, so an installed game keeps working. The new value only matters on a fresh activation, such as after the player clears user://, when it takes a second seat.
Can I use get_unique_id on a Web export?
No. Godot's docs say it returns an empty string and logs an error on Web. Send no fingerprint from Web builds, or skip activation there and validate with the key alone.