Making API Calls

The API expects data to be sent in a certain format. The API will send this data off to be processed and then return the results in a JSON header for your app to use.

If you’re curious what our JSON header responses look like, see our documentation on JSON header responses.

The API URL #

Our API URL is:

https://batchkeys.com/api.php

All API requests must be sent via HTTPS to this URL to ensure the integrity and security of the data being transferred. Be sure to always send API calls via https://and not http:// as non-secure HTTP requests will be denied.

API Request Headers #

All data is sent via request headers to the API URL. The API expects the following REQUIRED data sent with every call:

API Authorization key
License key
Either the domain or UUID that corresponds to that key

You can also send these optional headers:

Active
Consume

The names of these headers are as follows:

“auth” – Your unique API authorization key
“key” – The license key
“domain” – The domain name of the website (if applicable)
“uuid” – The UUID of the device (if applicable)
“active” – Set the key as active/inactive (optional)
“consume” – Consume or top up tokens on token-based keys (optional)

Spell them exactly as shown here. Here is an example of how to use them:

 curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'auth: ' . $authKey, // Set your unique API authorization key in the request headers
        'key: ' . $licenseKey, // Set the license key in the request headers
        'domain: ' . $domain, // Set the domain in the request headers
        'uuid: ' . $uuid // Set the UUID in the request headers
        'active: ' . $activation, // Sends manual key activation in the request headers (optional)
        'consume: ' . $tokenCost // Consumes or top up this many tokens (only for token-based keys)
    ));

Domain Vs UUID #

If your app runs as part of a website, like a plugin or a theme, then it will send the Domain information.

If your app is a game or other software that is installed on a PC with a Windows, Mac, or Linux operating system, then it will send the UUID information.

NOTE: You must send either a domain or a UUID, and you should only send one or the other. You cannot send nothing.

Before Making An API Call #

Before you make an API call you must first collect the necessary data.

Your Unique API Authorization Key #

This is the auth key that lets you use our API. It is unique to your account and can be found on your Dashboard. Always send it whenever you access our API or the connection will be refused.

General best practice is to always assign your API auth key to a variable in an env file and not inside the code itself. Various languages will use various ways of storing environmental variables but exactly how you do it is not important. The main takeaway is that our API will look for your auth key in the request headers, and if it’s found will proceed. If it’s not found an error will be returned.

The Key #

After someone purchase your app you will send them a license key. They can then enter this key into a form built into your app. This ensures the proper person received the key and the app was activated by them.

Your app should save the key as a variable inside a local file or database. You will then attach it to the request headers (more on this in a moment).

The Domain #

If applicable to your app, the domain should be included in the request headers. To see how and why, read our documentation on domain locking keys.

UUID #

If applicable to your app, the device’s UUID should be included in the request headers. To see how and why, read our documentation on generating a UUID and then the documentation on assigning keys to a UUID.

Activation #

Use this to optionally activate or deactivate the key manually. You do not have to send this to activate a key, as our API will recognize a new key and activate it automatically. This header is mostly used when you need to programmatically turn a key on or off inside your app, such as if an end user didn’t renew their subscription.

Turning the activation of a key on or off is the best way to handle non-payment events for subscription-based keys. Once a key has been (1. activated at least once and (2. has a domain/UUID assigned to it, the key will stay off if “active” is set to 0. Just be sure to turn it back on if they decide to renew. Read more about subscription-based keys.

// MUST be a 1 or 0. The API only accepts a 1 to activate a key or a 0 to deactivate a key:

$activate = 1;
// OR //
$activate = 0;

Token-Based Keys #

If your key has tokens tied to it and you would like to consume/add a token during this particular key check (for example, to charge a user for an action or to top up their tokens at the beginning of the month) then include the “consume” header. See our documentation on using token-based keys.

Example API Call #

Calling the API is actually very easy. Below is a minimum API call example using cURL.

$ch = curl_init($baseUrl);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
   'auth: ' . $authKey, 
   'key: ' . $licenseKey,
   'domain: ' . $_SERVER['HTTP_HOST'] 
));

$response = curl_exec($ch);
curl_close($ch);

Expected Responses #

There are several possible responses from an API call. These responses are sent via JSON headers back to you. Validation and error messages can be find in these responses.

A basic success message will respond as:

{"valid" : "1"}

A basic failure message will respond as:

{"valid" : "0"}

A basic error will respond as:

{"error" : "example error message (CODE: EXAMPLE)"}

For details, see our documentation on receiving a response and example JSON responses and error messages.

Using Best Practices When Making API Calls #

Here are a couple of fully working examples. The PHP example assumes it’s installed on a live web sever and therefore sends a domain to be assigned to the key. The Python example assumes it’s a standalone app installed on a Windows PC and therefore sends a UUID to be assigned to the key.

Note: We’ve left handling the response up to you. We highly recommend saving the license key and a simple Boolean variable such as “activated = true” into a local file. This way you can use this data for future checks, such as on startup.

If you are using UUIDs we recommend saving it into a secure, hidden file.

First, to follow best practices we set an environmental variable file to hold our sensitive data, such as the API URL and auth key. This is standard for all programming languages, but might vary slightly in its formatting based on the language or libraries you use.

BASE_URL=https://batchkeys.com/api.php
AUTH_KEY=000000000000000000

PHP Example #

In this PHP example we gather the license key from a user submitted form and then use cURL to preform the API call. We then handle the response back from the API. This example assumes it’s installed on a live web sever and therefore sends a domain to be assigned to the key.

<?php

// Load and parse the .env file
$envPath = __DIR__ . '.env';

if (file_exists($envPath)) {
    $env = file($envPath, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
    foreach ($env as $line) {
        list($name, $value) = explode('=', $line, 2);
        $_ENV[$name] = $value;
    }
} else {
    echo "Error: .env file not found.";
    exit;
}

// Get the base URL and API authentication key from the environment variables
$baseUrl = $_ENV['BASE_URL'];
$authKey = $_ENV['AUTH_KEY'];

// Ready message variable
$result = '';

// Check if the form has been submitted
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_POST['licenseKey'])) {
    
    // Set license key variable from a form
    $licenseKey = $_POST['licenseKey'];

    // Initialize cURL session
    $ch = curl_init($baseUrl);

    // Set options
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string instead of outputting it
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); // Enable SSL verification for security
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'auth: ' . $authKey, // Set your unique API authorization key in the request headers
        'key: ' . $licenseKey, // Set the license key in the request headers
        'domain: ' . $_SERVER['HTTP_HOST'] // Get the domain from the server, then set the domain in the request headers
    ));

    // Execute cURL session
    $response = curl_exec($ch);

    // Check for errors
    if (curl_errno($ch)) {
        // Handle error
        $result = 'cURL error: ' . curl_error($ch);
    } else {
        // Check HTTP response code
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

        if ($httpCode >= 200 && $httpCode < 300) {
            // Success, store the response
             $result = $response;

        } else {
            // Handle HTTP error
            $result = "HTTP error: " . $httpCode;
        }
    }

    // Close cURL session
    curl_close($ch);
}

?>

<!DOCTYPE html>
<html>
<body>
    <form action="" method="post">
            <input type="text" id="licenseKey" name="licenseKey" placeholder="Enter license key..." required>
            <input type="submit" value="Submit">
    </form>
</body>
</html>

Python Example #

Here below we have an example in Python that grabs the license key from a user-submitted form and calls the API. We then handle the response back from the API. This example assumes it’s a standalone app installed on a Windows PC and therefore sends a UUID to be assigned to the key.

import os
import uuid
import requests
import tkinter as tk
from tkinter import messagebox
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Get base URL and auth key from environment variables
base_url = os.getenv('BASE_URL')
auth_key = os.getenv('AUTH_KEY')

def submit_license_key():
    license_key = entry.get()

    # Generate a UUID (see our documentation for info about generating UUIDs)
    uuid_str = str(uuid.uuid4())

    headers = {
        'auth': auth_key,
        'key': license_key,
        'uuid': uuid_str
    }
    response = requests.get(base_url, headers=headers)
    messagebox.showinfo("Response", response.text)

# Set up the GUI
root = tk.Tk()
root.title("License Key Checker")

# Create a label and entry widget
label = tk.Label(root, text="Enter your license key:")
label.pack()

entry = tk.Entry(root)
entry.pack()

# Create a submit button
submit_button = tk.Button(root, text="Submit", command=submit_license_key)
submit_button.pack()

# Start the GUI event loop
root.mainloop()

There you have it. Calling the API is simple and requires minimum code and can be done in virtually all programming languages.

Getting Started

Integrations

Best Practices

The API URL #

API Request Headers #

Domain Vs UUID #

Before Making An API Call #

Your Unique API Authorization Key #

The Key #

The Domain #

UUID #

Activation #

Token-Based Keys #

Example API Call #

Expected Responses #

Using Best Practices When Making API Calls #

PHP Example #

Python Example #

Was this Helpful?

The API URL #

API Request Headers #

Domain Vs UUID #

Before Making An API Call #

Your Unique API Authorization Key #

The Key #

The Domain #

UUID #

Activation #

Token-Based Keys #

Example API Call #

Expected Responses #

Using Best Practices When Making API Calls #

PHP Example #

Python Example #

Was this Helpful?

How can we help?