API Libraries and Integrations

• .NET (source)
• Node.JS (source)
• Visual Studio Code (source)

If your language or tool of choice is not listed here, please let us know so we can continue to expand our API toolset.

Authentication

After navigating to the Luraph dashboard, go to the Account page, and uncollapse the API Details section. If you have not already generated an API key, please click the Generate API Token button. Please ensure you keep your API key private, as there is only one key per account, and anyone with your API key can access the API on your behalf. In order to send authenticated requests with the API, you must send your API key as the value of HTTP header Luraph-API-Key.

Request Structure

API Domain: https://api.lura.ph/

Current API Version: v1

Example URL: https://api.lura.ph/v1/obfuscate/new

The API is structured as a REST API. All request bodies and response bodies are represented as JSON bodies. The request body may be empty, and in that case, should be handled in the same manner as an empty JSON object.

Error Handling

Whenever a request is not successful, the endpoint will return a HTTP status code of 4xx or 5xx. Additionally, a JSON object with an errors array will be returned as the response body. There can be multiple errors, such as in the case that multiple parameters are incorrect. Each error object will contain an error message, and additionally, an optional parameter to associate the error message with.

Each endpoint displays a list of errors you may typically encounter while using the endpoint; however, this is not an exhaustive list of possible errors. Only use the error messages to display errors to the program operator, as these error messages are bound to change from time to time, and error messages will be added and deleted as the API updates.

Example Error Body:

{
  "errors": [
    {
      "param": "script",
      "message": "The maximum file size is 50MB."
    },
    {
      "param": "fileName",
      "message": "The maximum file name is 255 characters."
    },
    {
      "message": "There was a server error."
    }
  ]
}

Each endpoint may also return an optional warnings array alongside its normal response, which provides information to the developer about any information that may affect the correctness of their API integration. This field will always be formatted as an array of strings.

Example Warning Body:

{
  "warnings": [
    "memcorrupt is the best person ever!",
    "you're banned from luraph."
  ]
}

Endpoints

GET /obfuscate/nodes

Description: Get a list of available nodes to submit an obfuscation job to.

Response:

• recommendedId - The most suitable node to perform an obfuscation based on current service load and other possible factors.
• nodes - A list of all available nodes to submit obfuscation jobs to. The indented bullet points below assume that node is the semantic ID of the node, and opt is the semantic ID of the option.
  • nodes[node].version - The Luraph version available on the node, compliant with semver.org format (except the patch version identifier is optional).
  • nodes[node].cpuUsage - The current CPU usage of the node, ranging from 0-100%.
  • nodes[node].options[opt].name - A descriptive name for the option, used to display in
  • nodes[node].options[opt].description
  • nodes[node].options[opt].tier - The plan tier required for an option to be used. Can be either CUSTOMER_ONLY, or PREMIUM_ONLY. If your account doesn't have access to an option, the value provided to POST /obfuscate/new must be either a false boolean value, an empty string, or the first available option in the nodes[node].options[opt].choices array.
  • nodes[node].options[opt].type - Describes the type of value that this setting requires. Can be either CHECKBOX, DROPDOWN, or TEXT. If the type is CHECKBOX, the accepted value is a boolean. If the type is DROPDOWN, the accepted value is any option in the nodes[node].options[opt].choices array. If the type is TEXT, the accepted value is any string value.
  • nodes[node].options[opt].required - Marks a setting as required. If you are creating a user interface to integrate with Luraph, fields that are marked required should be explicitly set by the user, as they have a high chance of causing incorrect output if they are not set properly.
  • nodes[node].options[opt].choices - If the type is DROPDOWN, this will have a list of accepted values, else it will be an empty array.
  • nodes[node].options[opt].dependencies - Lists the required prerequisite status of other settings that are required to successfully enable this setting. This field is structured as an object containing option IDs as keys and a list of accepted values as the value. Each option must be set to one of the accepted values before this setting will accept a non-default value. If the dependencies are not met, it is acceptable to hide the option since it cannot be modified.

Example Response Body:

{
  "recommendedId": "main-1",
  "nodes": {
    "main-1": {
      "version": "13.3.7",
      "cpuUsage": 20.6,
      "options": {
        "OPTION1": {
          "name": "Luraph Is #1",
          "description": "Enable Luraph is the best obfuscator ever!",
          "tier": "CUSTOMER_ONLY",
          "type": "CHECKBOX",
          "required": false,
          "choices": [],
          "dependencies": {}
        },
        "OPTION2": {
          "name": "Best Luraph Developer",
          "description": "Pick the best Luraph developer ever!",
          "tier": "PREMIUM_ONLY",
          "type": "DROPDOWN",
          "required": true,
          "choices": ["memcorrupt", "bmcq"],
          "dependencies": {
            "OPTION1": [true]
          }
        }
      }
    },
    "main-2": {
      "version": "13.3",
      "cpuUsage": 92.1,
      "options": {
        "OPTION3": {
          "name": "Thank the Luraph team",
          "description": "Thank the Luraph Obfuscator team for creating this amazing obfuscator!",
          "tier": "CUSTOMER_ONLY",
          "type": "TEXT",
          "required": false,
          "choices": [],
          "dependencies": {}
        }
      }
    }
  }
}

Possible Errors:

• 503 - There are no obfuscation nodes available to handle your script.

GET /obfuscate/status/:jobId

Description: Endpoint that blocks until the obfuscation is complete. This endpoint has a timeout of 60 seconds, and has a maximum of 3 watchers per job. If you call it after the obfuscation is complete, it will return instantly. If there is no error in the script, this endpoint will return an empty response.

Response:

• error - If an error occured during the obfuscation process, the error will be returned here. (optional)

Example Response Body:

{
  "error": "Luraph:1: syntax error near <eof>"
}

Possible Errors:

• 403 - This obfuscation job does not belong to you.
• 404 - Obfuscation job not found.

GET /obfuscate/download/:jobId

Description: Download the obfuscation result of a job ID. The Content-Type, Content-Disposition, and Content-Length headers are set accordingly, with text/x-lua, the result file name, and the result file size, respectively. jobId should be set to the ID you received when you called /obfuscate/new.

Response: Returns the resulting lua script as a lua file, with no extra information attached.

Example Response Body:

LuraphVM("LPH|00112233445566778899AABBCCDDEEFF")

Possible Errors:

• 403 - This obfuscation job does not belong to you.
• 404 - Obfuscation job not found.
• 410 - This obfuscation job has expired, or otherwise is not available. (Obfuscation results are only available for 24h after your script obfuscation for security reasons.)

POST /obfuscate/new

Description: Submits a file for immediate obfuscation using the parameters specified below.

Parameters:

• fileName - A file name to associate with this script. The maximum file name is 255 characters.
• node - The node to queue this obfuscation job on. This must be one of the node IDs returned by the call to GET /obfuscate/nodes
• script - A base64 encoded representation of the script to obfuscate. The maximum file size is 50MB.
• options - An object containing keys that represent the option identifiers, and values that represent the desired settings. Unless enforceSettings is set to false, all options supported by the node must have a value specified, else the endpoint will error.
• useTokens - A boolean on whether you'd like to use tokens regardless of your active subscription.
• enforceSettings - A boolean on whether you'd like the options field to require every option requested by the server to be present with a valid value. If this is false, your integration will not break when invalid options are provided; however, updates that change Luraph's options will result in your integration using default settings when invalid values are specified. By default, this is set to true.

Example Request Body:

{
  "fileName": "luraph-best.lua",
  "node": "main-2",
  "script": "cHJpbnQnTFVSQVBIID4gQUxMISBMVVJBUEggIzEn==",
  "options": {
    "OPTION1": true,
    "OPTION2": "memcorrupt"
  }
}

Alternatively, you may opt to call this endpoint using Content-Type: multipart/form-data. In this case, you must upload your script using the script field, and pass the remaining aforementioned parameters as a JSON object in the data field.

Response:

• jobId - Returns the ID that references the obfuscation job created by this endpoint

Example Response Body:

{
  "jobId": "abcdef123456"
}

Possible Errors:

• 400 - The script parameter must be a base64-encoded script or multipart file upload. (param: script)
• 400 - The maximum file size is 50MB. (param: script)
• 400 - The file name parameter must be a non empty string. (param: fileName)
• 400 - The maximum file name is 255 characters. (param: fileName)
• 400 - The node parameter must be a non empty string. (param: node)
• 400 - This node does not exist, or is offline. (param: node)
• 400 - You do not have permission to use this node. (param: node)
• 400 - The options parameter must be an object. (param: options)
• 400 - The SETTING_NAME setting is missing. (param: options)
• 400 - The SETTING_NAME setting does not exist. (param: options)
• 400 - The SETTING_NAME setting is unavailable under your current access level. (param: options)
• 400 - The SETTING_NAME setting does not exist. (param: options)
• 400 - The SETTING_NAME cannot be applied because of unmet setting dependencies. (param: options)
• 400 - The useTokens parameter must be a boolean. (param: useTokens)
• 400 - The enforceSettings parameter must be a boolean. (param: enforceSettings)
• 402 - You do not have enough tokens to obfuscate. Please buy tokens, or a monthly subscription.
• 413 - Could not receive uploaded file: DECODE_ERROR
• 429 - The premium plan is limited to one concurrent obfuscation. Please try again once your existing job completes, or in 1 minute.
• 429 - Your subscription quota has been reached. Please upgrade to a higher plan, or contact support.