Authentication

GeckoGuard uses two authentication methods depending on the context: session tokens for dashboard management and API keys for programmatic access.

Session Tokens (Dashboard)

When logged into the GeckoGuard dashboard, your browser uses a session token (JWT) for all management operations — creating products, managing licenses, inviting team members, etc.

These tokens are managed automatically by the dashboard and are not exposed directly.

API Keys

API keys authenticate programmatic requests from your application. Each API key is scoped to a specific product and can have granular permissions.

Creating an API Key

1. Navigate to "API Keys" in your dashboard
2. Click "Create API Key"
3. Select the product this key belongs to
4. Give it a descriptive name (e.g., "Production License Validator")
5. Optionally configure permissions to restrict what the key can do
6. Copy the key immediately — it's only shown once!

Using API Keys

Include your API key in the Authorization header:

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-hwid'
  })
});

API Key Permissions

API keys support granular permissions. If no permissions are set, the key has full access to its product. Available permissions include:

When creating a key, pass permissions as an array:

// Via API
const response = await fetch('https://api.geckoguard.com/v1/dashboard/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_SESSION_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    productId: 'your-product-id',
    name: 'License Validator Only',
    permissions: ['license:authorize']
  })
});

Key Management

API keys can be:

• Renamed — update the display name
• Rotated — generate a new secret while keeping the same key ID
• Revoked — immediately disable a key
• Deleted — permanently remove a key

// Rotate an API key
await fetch('https://api.geckoguard.com/v1/dashboard/api-keys/KEY_ID/rotate', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_SESSION_TOKEN' }
});

// Revoke an API key
await fetch('https://api.geckoguard.com/v1/dashboard/api-keys/KEY_ID/revoke', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_SESSION_TOKEN' }
});

Rate Limiting

API requests are rate-limited to ensure fair usage:

• With API key: 120 requests per minute per IP
• Without API key: 60 requests per minute per IP

Rate limit headers are included in responses:

X-Ratelimit-Limit: 120
X-Ratelimit-Remaining: 115
X-Ratelimit-Reset: 1640995200

Security Best Practices

1. Never commit API keys to version control — use environment variables
2. Use minimal permissions — only grant the permissions your app needs
3. Rotate keys regularly — especially if compromised
4. Use different keys for different environments — separate dev/staging/production
5. Revoke unused keys — clean up old or compromised keys immediately
6. Monitor audit logs — check for suspicious activity on your keys

Environment Variables

Store API keys securely:

# .env
GECKOGUARD_API_KEY=your-api-key-here

// In your code
const apiKey = process.env.GECKOGUARD_API_KEY;

Error Responses

Invalid or missing API keys return 401 Unauthorized:

{
  "ok": false,
  "error": {
    "message": "Invalid or missing API key",
    "code": "UNAUTHORIZED"
  }
}

Insufficient permissions return 403 Forbidden:

{
  "ok": false,
  "error": {
    "message": "API key lacks required permission: license:authorize",
    "code": "FORBIDDEN"
  }
}