Clavem

Validate a license key in a Godot 4 game

Add an HTTPRequest node, POST JSON to /v1/licenses/validate, and await its request_completed signal. A 404 or 429 still arrives as RESULT_SUCCESS with a response_code, so branch on the code and on the valid flag in the body.

The shape of a Godot request

HTTPRequest is a node, and it must be in the scene tree before request() is called. It finishes through the request_completed(result, response_code, headers, body) signal. In GDScript 4 you can await that signal, so the check reads top to bottom and the game keeps running while it waits.

Unlike Unity, a 404 or 429 is not a transport error. result is RESULT_SUCCESS and response_code is 404. result is something else only when there was no HTTP answer: RESULT_CANT_RESOLVE, RESULT_TLS_HANDSHAKE_ERROR, RESULT_TIMEOUT and the rest.

An autoload that checks once per launch

Save this as license.gd and add it under Project Settings, Globals, Autoload with the name License. An autoload is created once, so scene changes never repeat the call.

extends Node

signal state_changed(state)
enum State { UNLICENSED, LICENSED, INVALID, NEEDS_NETWORK }

const BASE := "https://clavem.io"
const SAVE_PATH := "user://license.json"

var state: State = State.UNLICENSED
var _http: HTTPRequest

func _ready() -> void:
	process_mode = Node.PROCESS_MODE_ALWAYS  # a paused tree should not stall the request
	_http = HTTPRequest.new()
	_http.timeout = 8.0
	add_child(_http)
	if OS.has_feature("editor"):
		_set_state(State.LICENSED)  # play from the editor without a key
	else:
		check()

func check() -> void:
	var saved := _load()
	if saved.is_empty():
		_set_state(State.UNLICENSED)
		return
	var r := await _post("validate", {"license_key": saved.key, "instance_id": saved.instance})
	if r.status == 200:
		# Keep the new token even when the license is not valid: offline, it then says so.
		var token = r.body.get("token", "")
		if token is String and token != "":
			saved["token"] = token
			_save(saved)
		_set_state(State.LICENSED if r.body.get("valid", false) == true else State.INVALID)
	elif r.status == 404:
		_clear()  # unknown key, or this device was removed: ask for the key again
		_set_state(State.INVALID)
	else:
		# 0 (no answer), 400, 429, 5xx: trust the stored token while it is fresh.
		var fresh: bool = LicenseOffline.is_fresh(saved)  # from the offline verification page
		_save(saved)
		_set_state(State.LICENSED if fresh else State.NEEDS_NETWORK)

func _post(action: String, body: Dictionary) -> Dictionary:
	var headers := PackedStringArray(["Content-Type: application/json"])
	if not OS.has_feature("web"):
		headers.append("User-Agent: Inkwell/3.2")  # browsers will not let a page set this
	var err := _http.request(BASE + "/v1/licenses/" + action, headers, HTTPClient.METHOD_POST, JSON.stringify(body))
	if err != OK:  # ERR_BUSY, ERR_UNCONFIGURED (node not in the tree) and so on
		return {"status": 0, "body": {}, "retry_after": 0}
	var r: Array = await _http.request_completed  # [result, response_code, headers, body]
	if r[0] != HTTPRequest.RESULT_SUCCESS:
		return {"status": 0, "body": {}, "retry_after": 0}
	var parsed = JSON.parse_string((r[3] as PackedByteArray).get_string_from_utf8())
	return {"status": r[1], "body": parsed if parsed is Dictionary else {}, "retry_after": _header_int(r[2], "retry-after")}

func _header_int(headers: PackedStringArray, header_name: String) -> int:
	var prefix := header_name + ":"
	for h in headers:
		if h.to_lower().begins_with(prefix):
			return h.substr(prefix.length()).strip_edges().to_int()
	return 0

func _set_state(s: State) -> void:
	state = s
	state_changed.emit(s)

func _load() -> Dictionary:
	var f := FileAccess.open(SAVE_PATH, FileAccess.READ)
	if f == null:
		return {}
	var d = JSON.parse_string(f.get_as_text())
	return d if d is Dictionary else {}

func _save(d: Dictionary) -> void:
	var f := FileAccess.open(SAVE_PATH, FileAccess.WRITE)
	if f:
		f.store_string(JSON.stringify(d))

func _clear() -> void:
	DirAccess.remove_absolute(ProjectSettings.globalize_path(SAVE_PATH))

Connect to License.state_changed from your main menu and gate features there. The call runs once, in the background, and the menu appears at once.

Outcomes

response_code Meaning What check() does
200, valid: true Active or not yet activated Store the token, LICENSED
200, valid: false Expired or disabled Store the token, INVALID, show error
404 Unknown key, or this device’s activation was removed Clear the file, ask for the key
400 Malformed request Use the stored token
429 Retry-After: 60 Use the stored token, no retry this launch
503 Retry-After: 5 Use the stored token
0 result was not RESULT_SUCCESS Use the stored token

A real answer from the live API, captured on 19 November 2026, for a key that does not exist:

404  {"valid":false,"error":"license_key not found."}

retry_after is returned so your menu can say “try again in a minute”. Do not loop on it.

Godot-specific traps

  • One node, one request. request() returns ERR_BUSY while another is running. The autoload awaits each call, so calling check() twice quickly is the way to trip it.
  • JSON numbers are floats. JSON.parse_string reads every number with to_float(), so pid arrives as 75.0. == against an int still works, but an is int test fails.
  • Pausing. The node is processed by the tree. PROCESS_MODE_ALWAYS on the autoload, inherited by its child, keeps the request moving while you pause the game. I have not run this, so test a pause during startup.
  • Android. Enable the Internet permission in the Android export preset. Without it the engine blocks all network access.
  • Web exports. The request goes through the browser, which applies CORS. Godot’s HTTPClient docs say to allow the origin on the server, and the License API already sends Access-Control-Allow-Origin: *. OS.get_unique_id() is unavailable on Web, which matters for activation.

Where the file lives

user:// maps to %APPDATA%\Godot\app_userdata\[project_name] on Windows, ~/Library/Application Support/Godot/app_userdata/[project_name] on macOS and ~/.local/share/godot/app_userdata/[project_name] on Linux. The project name is part of the path. Rename the project after release and every player looks unlicensed. Set a custom user directory name once with application/config/use_custom_user_dir and leave it.

FileAccess.open_encrypted_with_pass needs a password, and the password lives in your exported project. It hides the file from a glance and no more. Protect the license with the signature on the token, not with secrecy.

Doing this with Clavem

The three calls and every status are in the API reference. The token the check stores is verified in offline verification for Godot, which also says what to do if your project has no C#.

Questions

Why does my second request fail with ERR_BUSY?

One HTTPRequest node handles one request at a time. Godot's docs say not to make simultaneous requests through a single node. Await the first request, or use a second node.

Do I need to embed a secret in the game?

No. The License API needs no authentication. The license key the player types is the credential, so nothing sensitive ships in the exported project.

Sources

  1. Godot docs, HTTPRequest class (checked November 2026)
  2. Godot docs, HTTPClient class, CORS note for Web exports (checked November 2026)
  3. Godot docs, file paths and user:// locations (checked November 2026)
  4. Godot docs, JSON class (checked November 2026)