App Variables

App Variables provide key-value storage that your application can read at runtime. Variables can be scoped globally (per product) or per license (per user).

Scopes

Global Variables

Global variables are shared across all users of a product. Use them for configuration your app needs at runtime — feature flags, server URLs, announcement messages, etc.

{
  "scope": "GLOBAL",
  "key": "server_url",
  "value": "https://game.example.com:7777"
}

User Variables

User variables are scoped to a specific license. Use them for per-user settings or data — user preferences, stored progress, custom config, etc.

{
  "scope": "USER",
  "licenseId": "license-uuid",
  "key": "user_level",
  "value": "42"
}

Managing Variables (Dashboard API)

List Variables

GET /v1/dashboard/app-variables/products/:productId?scope=GLOBAL|USER&licenseId=

Query parameters:

• scope — Filter by GLOBAL or USER
• licenseId — Filter by a specific license (for USER variables)

Create/Update a Variable

Variables are upserted — if the key already exists for the same scope+license, it's updated:

await fetch('/v1/dashboard/app-variables/products/PRODUCT_ID', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    scope: 'GLOBAL',       // or 'USER'
    // licenseId: '...',   // Required for USER scope
    key: 'server_url',
    value: 'https://game.example.com:7777'
  })
});

Bulk Upsert

Update up to 100 variables in a single request:

await fetch('/v1/dashboard/app-variables/products/PRODUCT_ID/bulk', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    variables: [
      { scope: 'GLOBAL', key: 'server_url', value: 'https://game.example.com:7777' },
      { scope: 'GLOBAL', key: 'motd', value: 'Welcome to v2.0!' }
    ]
  })
});

Delete a Variable

DELETE /v1/dashboard/app-variables/products/:productId/:variableId

Reading Variables (Client API)

Your application reads variables using the public endpoint with an API key (requires variable:read permission):

const response = await fetch(
  'https://api.geckoguard.com/v1/app-variables?productId=PRODUCT_ID&licenseId=LICENSE_ID',
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

const { data } = await response.json();
// data.global = { server_url: "https://...", motd: "Welcome!" }
// data.user   = { user_level: "42" }

The response separates global and user variables into two key-value maps for easy consumption.

Writing Variables (Client API)

Client applications can write user-scoped variables using the public PUT endpoint (requires variable:write permission on the API key):

const response = await fetch('https://api.geckoguard.com/v1/app-variables/public', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    productId: 'PRODUCT_ID',
    licenseId: 'LICENSE_ID',
    variables: {
      user_level: '42',
      last_server: 'us-east-1',
      settings: '{"fov":90,"sensitivity":2.5}'
    }
  })
});

Only user-scoped variables can be written from the client. Global variables can only be managed through the dashboard.

Deleting Variables (Client API)

Remove user-scoped variables by key (requires variable:write permission):

await fetch('https://api.geckoguard.com/v1/app-variables/public', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    productId: 'PRODUCT_ID',
    licenseId: 'LICENSE_ID',
    keys: ['last_server', 'settings']
  })
});

Limits

• Key: max 255 characters
• Value: max 10,000 characters
• Dashboard bulk upsert: max 100 variables per request
• Client write: max 50 variables per request

Use Cases

• Feature flags: Toggle features without app updates
• Server configuration: Dynamic server URLs, ports
• Announcements: Display messages to users
• Per-user data: Store lightweight user state server-side
• A/B testing: Different variable values for different license groups