Skip to main content

Games License Verification API

Games License Verification API

When you sell a game on 3DIMLI, each buyer receives a unique Order Item ID after purchase. This acts as their license key. Your game launcher or license server can call 3DIMLI's verification API to confirm whether a key is legitimate, which license tier was purchased, and whether the game is still published.

Who is this for?

This page is for developers listing games on 3DIMLI who want to add license activation and verification to their games or launchers. For a step-by-step integration walkthrough, see the Games License Integration Guide.

How It Works​

StepWhat happensWho
1Buyer purchases your game on 3DIMLIBuyer
2Buyer receives an Order Item ID (license key) via email and in their dashboard3DIMLI
3Buyer enters the license key in your launcherBuyer
4Your launcher sends the key to your license server, which forwards it to 3DIMLI authenticated with your seller tokenYour launcher + license server
53DIMLI responds: valid: true/false + productName + licenseName + productStatus3DIMLI
6Your launcher unlocks the game based on the license tier, optionally enforces device limitsYour launcher

3DIMLI answers one question: "Was this key legitimately purchased?"

You handle everything else: activation count, device binding, concurrent sessions, and feature gating based on licenseName on your own server.

API Reference​

Endpoint​

POST
https://www.3dimli.com/api/games/v1/verify

This endpoint requires a seller license-verification API token in the Authorization header. Generate one from Dashboard → Settings → API Tokens. The token is shown once at creation time — copy and store it securely.

Request Headers​

HeaderRequiredDescription
AuthorizationYesBearer <your_token> — your seller license-verification token
Content-TypeYesapplication/json

Request Body​

Request
{
  "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "product_slug": "/my-game"
}
FieldTypeRequiredDescription
keystring (UUID)YesThe buyer's Order Item ID (their license key)
product_slugstringYesYour game's URL slug from the store (e.g., /my-game)

The key must be a valid UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). The product_slug must be a non-empty string.

Slug format

The API normalizes the slug automatically. All of these are accepted: /my-game, my-game, games/my-game.

Responses​

200 OK
{
  "valid": true,
  "productName": "My Game",
  "licenseName": "Standard EULA",
  "productStatus": "PUBLISHED",
  "variant": {
    "title": "Deluxe"
  }
}

Response Fields​

FieldTypeDescription
validbooleantrue if the key is a legitimate, active, non-refunded purchase of this game
productNamestring | nullThe game title on 3DIMLI (e.g., "My Game")
licenseNamestring | nullThe license tier the buyer purchased (e.g., "Standard License", "Demo / Trial", "Open Source")
productStatusstringThe game's lifecycle status on 3DIMLI (e.g., PUBLISHED, UNPUBLISHED). Useful for launchers that gate updates or new sessions when the game is unpublished
variantobjectIncluded only when the purchased game has variants enabled. Contains title (e.g., the platform or edition the buyer selected)

When valid Returns false​

A license is invalid if any of the following are true:

  • The Order Item ID does not exist
  • The order status is not COMPLETED
  • The order has been refunded
  • The product_slug does not match the purchased game
  • The product is not a Games type
Security

The API never leaks information about why a key is invalid. It always returns { "valid": false } with no additional details.

Validation Sequence​

The API processes each request in this order:

StepCheckFailure response
1Authorization: Bearer <token> header present and non-empty401
2key is a valid UUID and product_slug is non-empty400 { valid: false }
3Token is valid and not revoked401
4Token owner has an active platform plan403 with subscription error
5Token owner is the seller of the product at games/<slug>403
6Client IP present400 { valid: false }
7Rate limit: 30 req / 60s / IP429 with Retry-After
8OrderItem exists with matching key AND game slug{ valid: false }
9Order item is in a verifiable state and not refunded{ valid: false }
10Product type is Games{ valid: false }

Steps 8–10 always return identical { valid: false } — no information is leaked about why it failed.

Status Codes​

CodeMeaning
200Request processed. Check the valid field for the result
400Missing or invalid fields (key must be a valid UUID, product_slug must be non-empty)
401Missing, malformed, invalid, or revoked token
403Token is valid but you don't own this game, or your platform subscription has lapsed
429Rate limit exceeded. Check Retry-After header
500Server error. Retry later
503Rate limiter unavailable. Retry later

Rate Limiting​

Limit30 requests per 60 seconds
ScopePer IP address (applied after token authentication)
HeadersRetry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Centralized license servers

If all your players' requests go through a single license server, those requests share one IP rate limit. Cache verification results on your server to stay within limits.

Generating Your Seller Token​

  1. Sign in to your seller account on 3DIMLI.
  2. Open Dashboard → Settings → API Tokens.
  3. Generate a license-verification token.
  4. Copy the raw token shown in the one-time dialog and store it in a secret manager (for example, your launcher's backend environment).
Keep the token server-side

Treat the token like a password. Do not ship it inside the player-facing game binary, where it can be extracted. Call the verify endpoint from your own license server (see examples below) and embed only the URL of your server in the game.

The token is bound to your seller account and can only verify keys for games you own. Verification requests for any other seller's game will return 403 Forbidden.

Finding Your Product Slug​

Your product slug is the URL path of your game in the store. Find it in the browser address bar when viewing your product page:

https://www.3dimli.com/games/<your-game-slug>
                              └── product_slug ┘

For example, if your game page is at https://www.3dimli.com/games/my-game, your product slug is /my-game (the API also accepts my-game or games/my-game).

note

The product slug is not a secret — it's visible in the store URL. It acts as a scope guard so a key purchased for Game A cannot be used to activate Game B.

Integration Examples​

Quick Test​

cURL
curl -X POST https://www.3dimli.com/api/games/v1/verify \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "product_slug": "/my-game"
  }'

License Server with Activation Limits​

The recommended pattern: your launcher talks to your license server, and your license server holds the seller token and calls 3DIMLI. This keeps the token off player machines.

server.js
const express = require("express");
const app = express();
app.use(express.json());

// ── Config ──────────────────────────────────────────────
const PRODUCT_SLUG = "/my-game";
const SELLER_TOKEN = process.env.DIMLI_SELLER_TOKEN; // never hardcode

// Map your license tier names to activation limits
const ACTIVATION_LIMITS = {
  "Standard License": 3,        // up to 3 devices
  "Demo / Trial License": 1,    // single demo device
  "Open Source License": -1,    // unlimited
};

// ── Store (use a database in production) ────────────────
const activations = new Map(); // key -> { licenseName, devices: Set }

// ── Activate ────────────────────────────────────────────
app.post("/activate", async (req, res) => {
  const { licenseKey, deviceId } = req.body;

  if (!licenseKey || !deviceId) {
    return res.status(400).json({ error: "licenseKey and deviceId required" });
  }

  // Verify with 3DIMLI
  const response = await fetch(
    "https://www.3dimli.com/api/games/v1/verify",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${SELLER_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ key: licenseKey, product_slug: PRODUCT_SLUG }),
    }
  );
  const result = await response.json();

  if (response.status === 401 || response.status === 403) {
    // Misconfiguration on your side - alert ops, don't blame the player
    console.error("3DIMLI auth failed:", result);
    return res.status(503).json({ error: "License service unavailable" });
  }

  if (!result.valid) {
    return res.status(403).json({ error: "Invalid license key" });
  }

  // Optional: refuse new activations when the game is unpublished
  if (result.productStatus === "UNPUBLISHED") {
    // Existing players can still play offline; up to you whether to gate new devices
  }

  // Get or create activation record
  let record = activations.get(licenseKey);
  if (!record) {
    record = { licenseName: result.licenseName, devices: new Set() };
    activations.set(licenseKey, record);
  }

  // Already activated on this device
  if (record.devices.has(deviceId)) {
    return res.json({ activated: true, licenseName: record.licenseName });
  }

  // Enforce activation limit
  const limit = ACTIVATION_LIMITS[record.licenseName] ?? 1;
  if (limit !== -1 && record.devices.size >= limit) {
    return res.status(403).json({
      error: `Activation limit reached (${limit}). Deactivate a device first.`,
    });
  }

  record.devices.add(deviceId);
  res.json({ activated: true, licenseName: record.licenseName });
});

// ── Deactivate ──────────────────────────────────────────
app.post("/deactivate", (req, res) => {
  const { licenseKey, deviceId } = req.body;
  const record = activations.get(licenseKey);
  if (record) record.devices.delete(deviceId);
  res.json({ deactivated: true });
});

app.listen(3000, () => console.log("Game license server on :3000"));

Client-Side Activation (In Your Game / Launcher)​

How the player's launcher calls your license server on startup. The seller token is not present here — only the URL of your license server.

license-client.js
const os = require("os");
const crypto = require("crypto");

function getDeviceId() {
  const raw = `${os.hostname()}-${os.platform()}-${os.cpus()[0]?.model}`;
  return crypto.createHash("sha256").update(raw).digest("hex").slice(0, 32);
}

async function activate(licenseKey) {
  const response = await fetch("https://your-license-server.com/activate", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ licenseKey, deviceId: getDeviceId() }),
  });

  const result = await response.json();

  if (result.activated) {
    // Save key locally so player doesn't re-enter it
    saveToStorage("licenseKey", licenseKey);
    unlockGame(result.licenseName);
    return true;
  }

  showError(result.error);
  return false;
}

Architecture​

                             ┌─────────────────────────────────┐
                             │        YOUR LICENSE SERVER       │
                             │  (holds seller Bearer token)    │
  ┌───────────────┐   POST   │                                 │   POST    ┌──────────────┐
  │               │ /activate│  1. Receive key + deviceId      │  + Bearer │              │
  │  GAME LAUNCHER│─────────▶│  2. Call 3DIMLI verify API   ───────────▶│   3DIMLI     │
  │               │          │  3. Cache result                │          │   API        │
  │  License key  │◀─────────│  4. Check activation limits     │◀─────────│              │
  │  + device ID  │  Result  │  5. Register device             │  valid   │  /games/v1/  │
  └───────────────┘          │  6. Return activated/denied     │ + status │  verify      │
                             │                                 │          └──────────────┘
                             │  YOUR RESPONSIBILITY:           │
                             │  • Activation limits            │
                             │  • Device tracking              │
                             │  • Concurrent session checks    │
                             │  • Feature gating               │
                             │  • Offline grace periods        │
                             │  • Token storage (server-side)  │
                             └─────────────────────────────────┘

Best Practices​

Caching​

Don't call the 3DIMLI API on every launcher start. Cache the result on your server and re-verify periodically.

Caching example
const PRODUCT_SLUG = "/my-game";
const CACHE_TTL = 24 * 60 * 60 * 1000; // 24 hours

async function verifyWithCache(licenseKey) {
  const cached = activations.get(licenseKey);

  // Use cache if fresh
  if (cached && Date.now() - cached.verifiedAt < CACHE_TTL) {
    return cached;
  }

  // Re-verify with 3DIMLI
  const res = await fetch("https://www.3dimli.com/api/games/v1/verify", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.DIMLI_SELLER_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ key: licenseKey, product_slug: PRODUCT_SLUG }),
  });
  const result = await res.json();

  if (!result.valid) {
    activations.delete(licenseKey); // Key revoked (e.g., refund)
    return null;
  }

  // Update cache timestamp
  if (cached) cached.verifiedAt = Date.now();
  return cached;
}

Offline & Refunds​

  • Offline grace period. If your server or 3DIMLI is unreachable, let the player continue for a set time (e.g., 7 days) before requiring re-verification. Single-player games should lean toward generous offline windows.
  • Refund handling. When a buyer gets a refund, 3DIMLI returns valid: false. On your next re-verify cycle, revoke access gracefully. Don't delete saved games or progress.

Device IDs​

Generate stable, unique device identifiers using hardware fingerprints (hostname + OS + CPU). Store the ID locally so it persists across sessions. Avoid identifiers that change after driver updates.

Handling productStatus: UNPUBLISHED​

If you unpublish your game on 3DIMLI, existing buyers still hold valid licenses. The API will keep returning valid: true for them but productStatus: "UNPUBLISHED". Decide your launcher policy: most games let existing players keep playing and only block new activations.

Rate Limits​

With 30 requests/minute per IP, a centralized server handling many players should cache aggressively. Batch or schedule re-verifications rather than verifying on every launch.

Token Hygiene​

  • Store the seller token in a secret manager or environment variable on your license server. Never commit it to source control.
  • Rotate the token from your API Tokens page if you suspect leakage.
  • A single token can verify any game you own — there's no need to mint a different token per title.

FAQ​

Where does the buyer find their license key?

The Order Item ID is available in:

  1. The purchase confirmation email from 3DIMLI
  2. Dashboard → Orders → expand order → License Product ID
  3. Dashboard → Downloads → license details → Item ID

All locations include a copy button for convenience.

What happens if a buyer gets a refund?

The API returns { "valid": false } for refunded orders. Your license server should handle this on the next re-verification by revoking access gracefully without deleting save data or progress.

Do I need an API token?

Yes. The games verify endpoint requires a seller license-verification token in the Authorization header. Generate one from Dashboard → Settings → API Tokens.

Can I put the token directly inside my game binary?

Strongly discouraged. Anyone who downloads your game can extract strings from the binary and use the token to verify keys for any of your titles. Always proxy verification through a license server you control and keep the token there.

Can one key work across multiple games?

No. Each key (Order Item ID) is tied to a specific game. The product_slug in the request must match the game the buyer purchased.

What does licenseName return?

The exact name of the license tier the buyer selected during purchase, for example "Standard License", "Demo / Trial License", "Open Source License", or any custom name you defined when creating your game.

What does productName return?

The title of your game on 3DIMLI, for example "My Game". This is included in valid responses so your launcher can display which game was activated.

What does productStatus return?

The lifecycle status of the game on 3DIMLI — typically PUBLISHED or UNPUBLISHED. Existing buyers retain valid licenses even after a game is unpublished; your launcher decides whether to gate new activations or new sessions in that case.

What is variant?

If your game has variants enabled (e.g., Standard / Deluxe / Platform-specific editions), the response includes the variant the buyer purchased. The field is omitted when the game has no variants.

What is product_slug and where do I find it?

The product slug is the URL path of your game in the 3DIMLI store. For example, if your game page is at https://www.3dimli.com/games/my-game, the slug is /my-game. It's not a secret — it prevents keys bought for one game from activating a different game.

On this page