VelaWare
API Reference & Integration Guide

VelaWare Developer Documentation

Deliver authorized, versioned Luau scripts and validate license credentials through VelaWare's cryptographically secured delivery endpoints.

Security & Credential Model

VelaWare establishes a strict boundary between public identifiers safe for client scripts and high-privilege credentials reserved for secure environments.

Project Public IDSafe For Client Code

Format: vela_proj_.... Non-sensitive identifier used by external loaders, clients, and configurations to declare which project is being accessed. Safe to expose publicly.

Project Secret API KeyServer-To-Server Secret

Format: vela_live_.... High-privilege secret. Shown only once upon creation in your dashboard. Stored as a SHA-256 hash. Never distribute inside client scripts.

Important: Protect Your Project Secret Key

The project API key (vela_live_...) authenticates requests to deliver scripts. It should be kept exclusively on your backend, bridge service, or private orchestrator.

Integration Lifecycle

The script delivery lifecycle follows a five-step authorization pipeline:

1

Generate a Project API Key

In your project dashboard, generate a secret API key and store it securely in your backend.

2

Issue a License Key

Create an active license key for your user or customer under the project's License Keys tab.

3

Obtain the Script ID

Select the target script in your project dashboard and copy its unique UUID.

4

Send Credentials to Deliver Endpoint

Dispatch the API key, license key, and script ID to POST /api/v1/script/deliver or use the loader helper.

5

Receive Authorized Payload

VelaWare validates the authorization chain and returns the latest version and raw source string.

POST/api/v1/script/deliver

Delivers the latest version of an authorized script payload. Validates project API credentials, license validity, and verifies that the license and script belong to the same authenticated project.

Request Body (JSON)

POST /api/v1/script/deliverjson
{
  "api_key": "vela_live_YOUR_PROJECT_API_KEY",
  "license_key": "VELA-XXXX-XXXX-XXXX-XXXX",
  "script_id": "YOUR_SCRIPT_UUID"
}

Success Response

HTTP 200 OK
Response 200 OKjson
{
  "success": true,
  "script_id": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "version": "1.0.0",
  "source": "-- Lua script payload\nprint(\"VelaWare script loaded\")"
}

Error Responses

StatusError StringDescription
400"Invalid request."Missing or non-string fields, malformed JSON, or legacy request format.
401"Invalid API credential."The API key format is invalid, does not exist, or has been revoked.
401"Invalid license."The license key was not found or is in an inactive state.
403"License revoked."The license key status is explicitly set to revoked.
403"License expired."The license key expiration timestamp has passed.
403"License is not valid for this project."The license exists but belongs to a different project than the API key.
404"Script not found."Script not found or does not belong to the authenticated project.
404"No script version available."Script exists under the project but has zero published versions.
500"Script delivery service is temporarily unavailable."Unexpected server error or temporary database connectivity failure.
POST/api/v1/license/validate

Validates a license key without requesting script source code. Checks existence, revocation status, and expiration dates.

Request Body (JSON)

POST /api/v1/license/validatejson
{
  "license_key": "VELA-XXXX-XXXX-XXXX-XXXX"
}

Success Response

HTTP 200 OK
Response 200 OKjson
{
  "valid": true,
  "status": "active"
}

Error Responses

StatusError StringDescription
400"Invalid request."Malformed JSON or missing license_key field.
401"Invalid license."The license key was not found in the database.
403"License revoked."The license key status has been set to revoked.
403"License expired."The license key has expired based on its expires_at timestamp.
500"License validation service is temporarily unavailable."Internal server error or database unavailability.

TypeScript Loader Integration

Use the official client helper in src/lib/velaware-loader.ts to safely communicate with the script delivery endpoint.

Loader Integration Exampletypescript
import { deliverScript } from "@/lib/velaware-loader";

async function loadScript() {
  const result = await deliverScript({
    baseUrl: "https://velaware.xyz",
    apiKey: "YOUR_PROJECT_API_KEY",
    licenseKey: "YOUR_LICENSE_KEY",
    scriptId: "YOUR_SCRIPT_ID",
  });

  if (result.success) {
    console.log(`Retrieved script version: ${result.version}`);
    // Raw script source code safely received as a string:
    // result.source
  } else {
    console.error(`Delivery failed: ${result.error}`);
  }
}

Important Integration Tips:

  • Never expose your apiKey in publicly decompilable client scripts.
  • Use bridge services or secure backend functions to mediate deliveries when distributing to unauthenticated users.
  • The loader does not evaluate code or execute scripts automatically; execution policy is strictly controlled by your application.

Ready to test your integration?

Navigate to your projects to generate API keys, create license keys, and manage scripts.

Open Dashboard