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()returnsERR_BUSYwhile another is running. The autoload awaits each call, so callingcheck()twice quickly is the way to trip it. - JSON numbers are floats.
JSON.parse_stringreads every number withto_float(), sopidarrives as75.0.==against an int still works, but anis inttest fails. - Pausing. The node is processed by the tree.
PROCESS_MODE_ALWAYSon 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.