Script Library

Script Library lets you write and maintain your own loader instead of using a FlareKey generated loader. It has its own endpoint:

https://library.flarekey.xyz

Every Library request is still authorized server-side: license, service, script, device, Discord, blacklist, and exact-build checks all apply. Your loader receives the authorized artifact and nothing else: no runtime key.

The host is API-only. Opening its root in a browser redirects to these docs; browser navigation to protected API paths returns 401 intentionally. Use the HTTP endpoints below from your loader or trusted backend.

What Library does and does not protect

Library delivery now includes a fresh, short-lived, one-use execution grant. A protected artifact must consume that grant before it initializes, so saving the downloaded source and replaying it later without a fresh authorized download fails closed.

This is an anti-offline-replay layer, not a claim that client code is undumpable. A capable attacker controlling a legitimate live client can still patch the guard, hook the request, race execution, or dump code after activation.

A generated FlareKey loader is stronger on both counts: it runs a session-bound, signed challenge exchange, and its builds carry the automatic guard. Choose Library when you need your own loader logic, not when you need the strongest protection available.

WARNING

Anything a customer can read in a custom loader is public. Keep API keys, runtime keys, service secrets, Discord bot credentials, and database credentials out of the loader.

Enable a script

Open the script editor in the FlareKey dashboard.
Enable Script Library / custom-loader mode.
Save an active, non-loader script.
If you use a saved custom loader, record its loaderId and bind it to the script's Library configuration.
Generate customer license keys for that script, or use a service-wide key if your licensing policy allows it.

Library mode is per script and off by default.

Scripts in Library mode are not given FlareKey's automatic TOTP guard when you save or rebuild them. Normal generated-loader scripts are unaffected.

Verify a license

Endpoint: POST https://library.flarekey.xyz/v1/licenses/verify

Send JSON, with Content-Type: application/json. Other content types and bodies over 16 KB are rejected.

The device ID must be stable per machine, at most 256 characters, and it feeds the service's normal HWID policy.

deviceId is asserted by the client

It is a string your loader chooses, not an attestation. FlareKey cannot verify it, and a customer who edits your loader can send anything. HWID policy raises the effort of casual key sharing; it does not prevent a determined user from moving a key between machines. Do not treat it as a hardware lock.

Verify itself takes no credential beyond the fields below. Anyone holding this tuple can mint tokens, so treat the license key as the whole of the customer's authorization and do not log it.

http

POST https://library.flarekey.xyz/v1/licenses/verify
Content-Type: application/json

{
  "serviceId": "svc_xxx",
  "scriptId": "scr_xxx",
  "loaderId": "sl_xxx",
  "licenseKey": "FLARE-XXXX-XXXX-XXXX-XXXX",
  "deviceId": "stable-device-id"
}

loaderId is optional for the protected-script artifact. Include it when the customer is using a saved custom loader; the returned token is then restricted to that exact loader artifact.

Success returns only the one-use token:

json

{
  "ok": true,
  "token": "libdl_xxx",
  "expiresIn": 45
}

Verify never returns source, a runtime key, or a reusable credential.

Download a custom loader

When verification includes loaderId, download the matching saved custom-loader artifact with the same one-use token:

http

GET https://library.flarekey.xyz/v1/script-loaders/sl_xxx/download
Authorization: Bearer libdl_xxx

The response is the loader artifact and includes X-Flare-Loader-Id, X-Flare-Artifact-Sha256, X-Flare-Artifact-Bytes, X-Flare-Artifact-Mac, and X-Flare-Artifact-Mac-Alg: HMAC-SHA256. A custom-loader download does not mint an execution grant; once the loader runs, it performs the normal target-script verify, download, integrity check, and exec_ activation flow itself. A public /loader URL is not the delivery contract; use this capability endpoint.

Limits

Beyond the per-IP limit, verification is capped per credential:

Cap	Ceiling
Verifies per minute, per license + device	10
Verifies per minute, per license (only when the service requires HWID binding)	30
Unused, unexpired tokens held at once, per license + device	10

A loader that verifies once per launch never approaches these. Exceeding one returns rate_limited.

Download the artifact

Endpoint: GET https://library.flarekey.xyz/v1/scripts/download

Send the token in the Authorization header:

http

GET https://library.flarekey.xyz/v1/scripts/download
Authorization: Bearer libdl_xxx

The response body is the script artifact. The token is single-use, so two requests cannot both consume it; verify again for each download.

Call download immediately. A token lasts 30–60 seconds, is frozen to the exact service, script, license, and build chosen at verification, and is pinned to the IP that verified it, so both calls must come from the same host.

The response also carries the build identity frozen at verification:

Header	Meaning
`X-Flare-Build-Id`	The build the token was issued against.
`X-Flare-Artifact-Sha256`	SHA-256 of the authorized artifact.
`X-Flare-Artifact-Bytes`	Byte length of the authorized artifact.
`X-Flare-Artifact-Mac`	HMAC-SHA256 of the exact response body, keyed by the raw `libdl_` token.
`X-Flare-Artifact-Mac-Alg`	The MAC algorithm; currently `HMAC-SHA256`.
`X-Flare-Execution-Token`	One-use execution grant for this exact delivered artifact.
`X-Flare-Execution-Expires-In`	Seconds before the execution grant expires (20 by default).

Before running or saving the artifact, verify its byte length and SHA-256, then verify X-Flare-Artifact-Mac as HMAC-SHA256 over the exact response body using the raw libdl_ token as the key. The MAC is the integrity/authenticity check; the hash and byte count are secondary consistency checks. Never log or persist the token after the request.

Do not put the token in a query string, URL path, cookie, or log. Query-carried tokens and runtime keys are rejected.

If the build is retired, the script or service is disabled, the license changes, the device no longer matches, or a Discord/blacklist policy fails, the request fails and never falls back to another build.

Execution grant scope and lifetime

A successful download mints exactly one execution grant, derived from the download token that was just consumed. The server stores only a hash of it; the raw value exists in the X-Flare-Execution-Token response header and nowhere else.

The grant is frozen to the delivery it was issued for:

Bound to	Effect
Service, script, license	Activation recomputes the same license, service, script, device, Discord, and blacklist checks that verification ran. A state change between download and activation fails the activation.
Build ID and artifact SHA-256, byte length, and format version	The grant only activates against the exact artifact that was delivered. Rebuilding or retiring the build invalidates it.
The originating download token	One download, one grant. A grant cannot be reissued without a fresh verify and download.
The verifying IP	Activation must come from the same host that verified and downloaded.

Lifetime is short by design:

Credential	Lifetime	Uses
Download token (`libdl_`)	30–60 seconds	1
Execution grant (`exec_`)	About 20 seconds	1

Because the whole chain is verify → download → activate, the grant only has to survive one HTTP round trip inside the running executor. Do not add retry loops, disk caching, or user prompts between download and activation; the grant will expire.

Grants are also revoked server-side, without waiting for expiry, when the service, license, or script is revoked, disabled, rotated, or has its HWID reset. Revocation only affects grants that have not been used yet, so a session already running is not killed mid-execution.

Hand the grant to the downloaded source

Read the execution header case-insensitively because executor HTTP APIs may normalize header names. Stage 2 must place the grant in the temporary global immediately before running the downloaded chunk. It must not clear the global before the chunk begins; the prependable source guard clears it on its first lines.

The essential sequence is:

lua

local source, executionToken = downloadScript(downloadToken)

local env = getgenv()
env.__FlareExecution = executionToken
executionToken = nil

local chunk, compileError = loadstring(source)
source = nil
if type(chunk) ~= "function" then
    env.__FlareExecution = nil
    error(compileError or "Script compilation failed", 0)
end

return chunk()

downloadScript must return both response.Body and X-Flare-Execution-Token, and fail closed when either is absent. A complete drop-in tail, assuming verifyLicense() already performs your existing Library checks:

lua

local function responseHeader(response, wanted)
    local headers = type(response) == "table" and (response.Headers or response.headers) or nil
    if type(headers) ~= "table" then return nil end
    wanted = string.lower(wanted)
    for name, value in pairs(headers) do
        if string.lower(tostring(name)) == wanted then return tostring(value) end
    end
    return nil
end

local function downloadScript(downloadToken)
    local response = request({
        Url = "https://library.flarekey.xyz/v1/scripts/download",
        Method = "GET",
        Headers = { ["Authorization"] = "Bearer " .. downloadToken }
    })
    downloadToken = nil

    if type(response) ~= "table" then error("Script download failed", 0) end
    local status = tonumber(response.StatusCode or response.statusCode or response.Status or response.status)
    if status ~= 200 then error("Script download failed", 0) end

    local source = response.Body or response.body or response.ResponseBody or response.responseBody or response.Data or response.data
    local executionToken = responseHeader(response, "X-Flare-Execution-Token")
    if type(source) ~= "string" or source == "" then error("Script download failed", 0) end
    if type(executionToken) ~= "string" or executionToken == "" then error("Missing execution authorization", 0) end
    return source, executionToken
end

local downloadToken = verifyLicense()
local source, executionToken = downloadScript(downloadToken)
downloadToken = nil

local env = getgenv()
env.__FlareExecution = executionToken
executionToken = nil

local chunk, compileError = loadstring(source)
source = nil
if type(chunk) ~= "function" then
    env.__FlareExecution = nil
    error(compileError or "Script compilation failed", 0)
end

return chunk()

Activate before customer initialization

Endpoint: POST https://library.flarekey.xyz/v1/scripts/:scriptId/activate

http

POST https://library.flarekey.xyz/v1/scripts/scr_xxx/activate
Authorization: Bearer exec_xxx
Content-Type: application/json

{}

Success is only:

json

{ "ok": true }

The server hashes the bearer token, rechecks the current license, service, script, and exact build/artifact, then atomically marks the grant used. Exactly one request can win a race. The token never belongs in a URL, log, analytics event, file, or persistent client setting.

Activation is rate limited to 120 requests per minute per IP and returns rate_limited above that. A normal launch calls it once.

The request must carry no query string. Activation with any query parameter is rejected as token_invalid before the token is looked at, so never append cache-busting or tracking parameters to the URL.

Executor requirements

The guard aborts the script rather than running unauthorized when the executor cannot complete activation. It needs both:

getgenv(), to read the grant Stage 2 placed in the shared global environment.
A global request function accepting a table with Url, Method, Headers, and Body.

If either is missing, or the HTTP call throws, or the response status is anything other than 200, the guard returns before the customer source runs. There is no retry and no fallback path.

Prependable source guard

Paste the guard below at the very top of your source, before it is obfuscated, and replace __FLARE_SCRIPT_ID__ with your Library script ID. Nothing else in it changes between scripts.

The guard reads getgenv().__FlareExecution, clears the global immediately, performs one activation request, clears its local token reference, and returns before customer initialization unless the server responds with HTTP 200. It never prints or persists the token and does not retry rejected grants.

lua

do
    local env = type(getgenv) == "function" and getgenv() or nil
    if type(env) ~= "table" then return end
    local executionToken = env.__FlareExecution
    env.__FlareExecution = nil
    if type(executionToken) ~= "string" or executionToken == "" then return end
    local requestFn = request
    if type(requestFn) ~= "function" then executionToken = nil return end
    local ok, response = pcall(requestFn, {
        Url = "https://library.flarekey.xyz/v1/scripts/__FLARE_SCRIPT_ID__/activate",
        Method = "POST",
        Headers = {
            ["Authorization"] = "Bearer " .. executionToken,
            ["Content-Type"] = "application/json"
        },
        Body = "{}"
    })
    executionToken = nil
    if not ok or type(response) ~= "table" then return end
    local status = tonumber(response.StatusCode or response.statusCode or response.Status or response.status)
    if status ~= 200 then return end
end

Your dashboard event log records are recorded as library_execution_issued, library_execution_activated, library_execution_replayed, library_execution_expired, and library_execution_failed; raw tokens and source are never event metadata.

Optional manual TOTP

If your loader needs the current service TOTP, request it directly.

This is optional and only available when TOTP is configured for the service. The endpoint authenticates with the same short-lived libdl_ token used for Library delivery; do not send totpSecret from the client. The server reads the configured service secret internally. Call this endpoint from your loader only when the service policy requires it.

Endpoint: POST https://library.flarekey.xyz/v1/scripts/:scriptId/totp

http

POST https://library.flarekey.xyz/v1/scripts/scr_xxx/totp
Authorization: Bearer libdl_xxx
Content-Type: application/json

{
  "serviceId": "svc_xxx"
}

Response:

json

{
  "ok": true,
  "totp": "123456",
  "period": 30,
  "digits": 6,
  "expiresIn": 17
}

The token must authorize the service and script, and the script must be Library-enabled. If TOTP is not configured, the endpoint returns totp_unavailable. The normal verify/download flow does not need this endpoint.

Errors

Failures return JSON with ok: false and a stable error string.

Error	Meaning	Next action
invalid_request	A required field is missing or malformed.	Fix the request before retrying.
invalid_service / invalid_script / invalid_loader	The service, script, or requested custom loader is unavailable for Library delivery.	Check the dashboard configuration and loader ID.
license_invalid / license_disabled / license_expired	The customer key cannot authorize the request.	Ask the customer for an active key.
wrong_script	The key is bound to a different script in this service.	Use the key's bound script.
device_mismatch	The device does not satisfy the HWID policy.	Reuse the correct stable device ID or reset the device.
token_invalid / token_expired / token_used	The token cannot be consumed, or it is being redeemed from a different IP than verified it.	Verify again for a new token, from the host that will download.
artifact_retired	The build captured at verification is no longer current.	Verify again after selecting an active build.
artifact_not_ready	The selected artifact is not ready for delivery.	Select or build an active artifact, then verify again.
wrong_script / license_invalid / script_invalid	The execution grant no longer matches an active authorization context.	Start a fresh verify and download after correcting the state.
artifact_invalid	The exact build/artifact delivered with the execution grant is no longer valid.	Download the current authorized artifact again.
totp_unavailable	TOTP is not configured or is unavailable for this service.	Configure TOTP or omit the optional request.
rate_limited	A per-IP or per-credential limit was exceeded.	Back off before retrying.

Treat authorization failures as terminal for that attempt. Do not loop on a rejected token.

Script Library ​

Enable a script ​

Verify a license ​

Download a custom loader ​

Limits ​

Download the artifact ​

Execution grant scope and lifetime ​

Hand the grant to the downloaded source ​

Activate before customer initialization ​

Executor requirements ​

Prependable source guard ​

Optional manual TOTP ​

Errors ​

Script Library

Enable a script

Verify a license

Download a custom loader

Limits

Download the artifact

Execution grant scope and lifetime

Hand the grant to the downloaded source

Activate before customer initialization

Executor requirements

Prependable source guard

Optional manual TOTP

Errors