Quick Start

This guide will walk you through creating your first organization, product, and license in GeckoGuard.

Prerequisites

  • A GeckoGuard account (Sign up here)
  • An API key (created in your dashboard)

Step 1: Create an Organization

Organizations are the top-level containers for your products and licenses. Each organization can have multiple team members and products.

  1. Log in to your GeckoGuard dashboard
  2. Click "Create Organization" or select an existing one
  3. Give your organization a name (e.g., "My Software Company")

Step 2: Create a Product

Products represent the software applications you want to protect with licenses.

  1. Navigate to your organization
  2. Go to the "Products" section
  3. Click "Create Product"
  4. Fill in the product details:
    • Name: Your product name (e.g., "My Desktop App")
    • Default License Policy: Configure default HWID, IP, concurrency limits, and reset budgets

Step 3: Generate an API Key

API keys authenticate your requests to the GeckoGuard API.

  1. Go to "API Keys" in your dashboard
  2. Click "Create API Key"
  3. Select the product it belongs to
  4. Optionally set permissions (e.g., license:authorize, license:read)
  5. Important: Copy the key immediately — you won't be able to see it again!

Step 4: Create Your First License

Create a license through the dashboard UI, or programmatically via the API:

const response = await fetch('https://api.geckoguard.com/v1/dashboard/orgs/YOUR_ORG_ID/licenses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_SESSION_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    productId: 'your-product-id',
    // key: 'CUSTOM-KEY-123',    // Optional — auto-generated if omitted
    // expiresAt: null,           // Fixed expiry date (ISO 8601)
    // expiresAfterDays: 30,      // Relative expiry (days after first activation)
    // expirationMode: 'never',   // 'never' | 'fixed' | 'afterActivation' | 'both'
    // policyOverride: { ... },   // Override product default policy
    // count: 1                   // Bulk create up to 500 licenses
  })
});

const result = await response.json();
console.log('License created:', result.data);

Step 5: Validate a License

In your application, validate licenses using the authorization endpoint. This endpoint requires an API key with license:authorize permission:

const response = await fetch('https://api.geckoguard.com/v1/licenses/authorize', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    productId: 'your-product-id',
    licenseKey: 'LICENSE-KEY-123',
    hwid: 'device-hardware-id',   // Optional: for hardware binding
    ip: '192.168.1.1',            // Optional: for IP restrictions
    deviceId: 'device-uuid',      // Optional: device identifier
    sessionId: 'unique-session',  // Optional: for concurrency limits
    dryRun: false                 // Optional: test without persisting changes
  })
});

const result = await response.json();
if (result.allow) {
  console.log('License is valid!');
  console.log('Expires at:', result.effectiveExpiresAt);
  console.log('Remaining limits:', result.limits.remaining);
} else {
  console.error('Denied:', result.reasonCode, result.message);
}

Successful Response

{
  "ok": true,
  "allow": true,
  "reasonCode": "ALLOW",
  "message": "Authorization granted",
  "policy": { "summary": "Authorization granted" },
  "limits": {
    "remaining": {
      "hwid": "unlimited",
      "ip": "unlimited",
      "concurrency": "unlimited"
    }
  },
  "activatedAt": "2025-01-15T10:30:00.000Z",
  "effectiveExpiresAt": "2025-12-31T23:59:59.000Z",
  "expiresAt": "2025-12-31T23:59:59.000Z",
  "expiresAfterDays": null
}

Denied Response

{
  "ok": false,
  "allow": false,
  "reasonCode": "HWID_MISMATCH",
  "message": "Hardware ID does not match bound device"
}

Next Steps