Skip to main content

❓ Frequently Asked Questions

Common questions and answers about TKI Auth implementation, configuration, and usage.

API & Integration​

Why doesn't TKI Auth automatically detect the client's IP address?​

Question: Why do I need to provide the IP address in the API request? Can't the server automatically detect it?

Answer: TKI Auth requires you to explicitly provide the IP address in the API request body for several important reasons:

Minecraft Servers & Port-Specific Usage​

Many developers, especially in the Minecraft community, want to restrict license usage to specific servers identified by IP:PORT combinations. For example:

  • 192.168.1.100:25565 (Main server)
  • 192.168.1.100:25566 (Test server)
  • 192.168.1.100:25567 (Development server)

By requiring explicit IP provision, you can implement port-specific licensing where each server port has its own license restrictions.

Proxy & Load Balancer Support​

When using reverse proxies, CDNs, or load balancers:

  • The server might see the proxy's IP instead of the client's real IP
  • You can provide the actual client IP from X-Forwarded-For headers
  • Gives you control over which IP gets tracked and limited

Multi-Server Environments​

For applications running across multiple servers:

  • Each server can identify itself with its own IP
  • Enables server-specific license tracking
  • Supports complex network topologies

Custom IP Logic​

You can implement custom IP resolution logic:

// Example: Custom IP detection
const clientIP = req.headers['x-forwarded-for']?.split(',')[0] || 
                 req.headers['x-real-ip'] || 
                 req.connection.remoteAddress ||
                 '127.0.0.1';

// Send to TKI Auth
const response = await fetch('/api/license/auth', {
  body: JSON.stringify({
    data: {
      // ... other fields
      ip: clientIP, // Your custom IP logic
    }
  })
});

Testing & Development​

Explicit IP provision makes testing easier:

  • Use 127.0.0.1 for local development
  • Use specific test IPs for staging environments
  • Override IP for testing different scenarios

Can I use TKI Auth with multiple applications?​

Question: I have multiple products. Can they all use the same TKI Auth instance?

Answer: Yes! TKI Auth is designed for multi-product environments:

Product-Specific Licenses​

Regular licenses are tied to specific products:

// App 1 license only works for "MyGameMod"
{
  product: "MyGameMod",
  version: "1.0.0",
  licensekey: "TKI-ABC12-DEF34"
}

// App 2 license only works for "MyWebApp"  
{
  product: "MyWebApp", 
  version: "2.1.0",
  licensekey: "TKI-XYZ78-GHI90"
}

Staff Licenses (Universal)​

Staff licenses work across ALL products:

// This license works for any product
{
  product: "AnyProduct",
  version: "AnyVersion", 
  licensekey: "TKI-STAFF-12345" // Staff license
}
warning

Be careful who you provide a Staff License to!

Configuration & Setup​

Why are some Discord commands not working?​

Question: Users can't use certain commands even though they have roles assigned.

Answer: Check these common configuration issues:

Role Hierarchy​

Ensure your bot's role is positioned higher than the roles it needs to manage:

  1. Go to Server Settings → Roles
  2. Drag the bot's role above client/user roles
  3. Verify the bot has "Manage Roles" permission

Role ID Format​

Role IDs must be strings in arrays:

# ✅ Correct
CreateLicense: ["1234567890", "0987654321"]

# ❌ Wrong
CreateLicense: [1234567890, 0987654321]  # Numbers without quotes
CreateLicense: "1234567890"              # String instead of array

Permission Verification​

Test role configurations:

  1. Check role IDs are correct (Developer Mode → Right-click role → Copy ID)
  2. Verify users actually have the assigned roles
  3. Confirm bot permissions in the channel

Security & Best Practices​

How secure is TKI Auth?​

Question: What security measures does TKI Auth implement?

Answer: TKI Auth includes multiple security layers:

API Security​

  • API Key Authentication - All requests require valid API key
  • Rate Limiting - Prevents brute force and DDoS attacks
  • IP Validation - Track and limit IP addresses per license
  • HWID Protection - Hardware-based license binding

Blacklist Protection​

  • IP Blacklisting - Block malicious IP addresses
  • HWID Blacklisting - Block compromised hardware IDs
  • License Blacklisting - Revoke specific license keys
  • Automatic Blocking - Track and count blocked attempts

Database Security​

  • MongoDB Integration - Secure, scalable database storage
  • Encrypted Connections - SSL/TLS for database communication
  • Access Control - Role-based permissions system

Discord Integration Security​

  • Ephemeral Messages - Sensitive data only visible to authorized users
  • Role-Based Access - Granular permission control
  • Audit Logging - Complete activity tracking

What are the best practices for API key management?​

Question: How should I handle API keys securely?

Answer: Follow these security best practices:

API Key Generation​

# Generate strong API keys (32+ characters)
openssl rand -base64 32

Secure Storage​

# Use environment variables
export TKI_API_KEY="your-secure-api-key-here"
# Reference in config
ApiSettings:
  APIKey: "${TKI_API_KEY}"

Production Security​

  • Never commit API keys to version control
  • Use different keys for development/staging/production
  • Monitor API usage for unusual patterns
  • Limit API access to authorized IPs only

Troubleshooting​

My licenses aren't working after changing settings​

Question: I updated my configuration but existing licenses stopped working.

Answer: Configuration changes affect different systems differently:

License Generation Settings​

Changes to license format (prefix, length, etc.) only affect NEW licenses:

# Old setting
LicensePrefix: "OLD-"

# New setting  
LicensePrefix: "NEW-"

# Result: 
# - Existing licenses: "OLD-ABC12-DEF34" (still valid)
# - New licenses: "NEW-ABC12-DEF34"

API Settings Changes​

API changes affect all requests immediately:

  • API Key changes - Update all applications immediately [After Restart]
  • Rate limit changes - Take effect on next minute [After Restart]
  • HWID requirement changes - Affect all new requests [After Restart]

Product Version Changes​

Version updates require application updates:

# If you change product version from 1.0.0 to 2.0.0
# All API requests must use the new version
{
  "product": "MyApp",
  "version": "2.0.0",  // Must match current version
  "licensekey": "TKI-ABC12-DEF34"
}

Advanced Logging isn't creating forum threads​

Question: I enabled Advanced Logging but no forum threads are being created.

Answer: Check these common issues:

Forum Channel Setup​

  1. Channel Type: Must be a Forum Channel (not regular text channel)
  2. Channel ID: Verify the ID is correct
  3. Bot Permissions: Bot needs "Create Public Threads" permission
  4. Channel Access: Bot must be able to see and access the channel

Configuration Check​

Logging:
  Enabled: true  # Must be true
  AdvancedLogging:
    Enabled: true  # Must be true
    ForumChannelID: "1234567890"  # Must be valid forum channel ID
    StoreLicenses: true  # Enable license logging
    StoreRequests: true  # Enable request logging

Testing Advanced Logging​

  1. Create a new license for a user
  2. Make an API request with that license
  3. Check if forum thread appears
  4. Verify thread contains expected logs

Rate limiting is too restrictive​

Question: Legitimate users are being rate limited. How do I adjust this?

Answer: Tune rate limiting based on your usage patterns:

Analyze Usage Patterns​

  • Monitor typical request frequency
  • Identify peak usage times
  • Consider application architecture (frequent vs. batched requests)

Adjust Rate Limits​

ApiSettings:
  Ratelimit:
    Enabled: true
    Max: 500  # Increase from default 100

License Management​

Can users have multiple licenses?​

Question: Can a single user have multiple licenses for different products?

Answer: Yes, users can have multiple licenses:

Multiple Products​

// User can have licenses for different products
User ID 123456789:
- License 1: TKI-ABC12 for "GameMod"
- License 2: TKI-DEF34 for "WebApp" 
- License 3: TKI-GHI56 for "MobileApp"

Multiple Licenses Per Product​

// User can have multiple licenses for same product
User ID 123456789:
- License 1: TKI-ABC12 for "GameMod" (expires 2024-12-31)
- License 2: TKI-DEF34 for "GameMod" (expires 2025-06-30)

Staff + Regular Licenses​

// User can have both staff and regular licenses
User ID 123456789:
- Staff License: TKI-STAFF123 (works for all products)
- Regular License: TKI-ABC12 for "SpecificProduct"

How do I handle license expiration?​

Question: What happens when licenses expire, and how should I handle it?

Answer: TKI Auth automatically handles expiration:

Automatic Expiration​

// Expired license API response
{
  "message": "License has expired!",
  "status_overview": "failed"
}

Grace Period Implementation​

// Implement grace period in your application
async function validateLicense(licenseData) {
  const result = await authenticateWithTKI(licenseData);
  
  if (result.status_overview === 'failed' && 
      result.message.includes('expired')) {
    
    // Check if within grace period
    const expireDate = new Date(result.expire_date);
    const gracePeriod = 7 * 24 * 60 * 60 * 1000; // 7 days
    
    if (Date.now() - expireDate.getTime() < gracePeriod) {
      // Allow usage with warning
      return {
        valid: true,
        warning: 'License expired - grace period active'
      };
    }
  }
  
  return result;
}

License Renewal​

// Extend license expiry
/license edit
// Select license → Modify expiry date

What's the difference between regular and staff licenses?​

Question: When should I use staff licenses vs regular licenses?

Answer: Each license type serves different purposes:

Regular Licenses​

  • Product-specific: Only work for the assigned product
  • Version-locked: Must match exact product version
  • User licenses: For end customers
  • Restricted access: Follow normal validation rules
// Regular license validation
{
  "product": "GameMod",      // Must match exactly
  "version": "1.0.0",        // Must match exactly  
  "licensekey": "TKI-ABC12"  // Product-specific license
}

Staff Licenses​

  • Universal access: Work for ALL products
  • Version-flexible: Bypass version checking
  • Administrative: For team members and testing
  • Elevated privileges: Skip normal restrictions
// Staff license validation
{
  "product": "AnyProduct",   // Can be any product
  "version": "AnyVersion",   // Version ignored
  "licensekey": "TKI-STAFF123"  // Staff license
}