> ## Documentation Index
> Fetch the complete documentation index at: https://docs.authforge.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# App & License Variables

> Use key-value variables to deliver feature flags, remote config, and per-user settings through the AuthForge SDK.

Variables are key-value pairs delivered to your application through the SDK during authentication. There are two types: **app variables** (global) and **license variables** (per-user).

## App Variables

App variables are set per app and delivered to **every** SDK client during authentication in the `appVariables` field of the signed payload.

### Use cases

| Variable            | Value                      | Purpose                         |
| ------------------- | -------------------------- | ------------------------------- |
| `"maintenanceMode"` | `true`                     | Disable the app remotely        |
| `"maxUploadSizeMb"` | `50`                       | Remote config without an update |
| `"motd"`            | `"v2.0 releasing Friday!"` | Display a message to all users  |
| `"minVersion"`      | `"1.5.0"`                  | Block outdated clients          |

### Setting app variables

**Dashboard:** App Settings → Variables

**Developer API:**

```bash theme={null}
# Get current variables
curl https://api.authforge.cc/v1/apps/YOUR_APP_ID/variables \
  -H "Authorization: Bearer af_live_your_key"

# Set variables (replaces all variables)
curl -X PUT https://api.authforge.cc/v1/apps/YOUR_APP_ID/variables \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "maintenanceMode": false,
    "maxUploadSizeMb": 50,
    "motd": "Welcome to v2.0!",
    "minVersion": "1.5.0"
  }'
```

### Reading app variables in the SDK

<CodeGroup>
  ```python Python theme={null}
  if client.login(license_key):
      variables = client.app_variables

      if variables.get("maintenanceMode"):
          print("Server is under maintenance. Try again later.")
          exit(0)

      motd = variables.get("motd")
      if motd:
          print(f"Notice: {motd}")
  ```

  ```csharp C# theme={null}
  if (client.Login(licenseKey))
  {
      var variables = client.AppVariables;

      if (variables.TryGetValue("maintenanceMode", out var maint) && maint is true)
      {
          Console.WriteLine("Server is under maintenance.");
          Environment.Exit(0);
      }

      if (variables.TryGetValue("motd", out var motd))
      {
          Console.WriteLine($"Notice: {motd}");
      }
  }
  ```

  ```cpp C++ theme={null}
  if (client.Login(key)) {
      auto variables = client.GetAppVariables();

      if (variables.count("maintenanceMode") && variables["maintenanceMode"] == "true") {
          std::cout << "Server is under maintenance." << std::endl;
          return 0;
      }
  }
  ```
</CodeGroup>

***

## License Variables

License variables are set per license and delivered **only** to that specific license holder in the `licenseVariables` field.

### Use cases

| Variable         | Value                           | Purpose                     |
| ---------------- | ------------------------------- | --------------------------- |
| `"plan"`         | `"pro"`                         | Feature gating by plan tier |
| `"maxProjects"`  | `10`                            | Per-user resource limits    |
| `"customerName"` | `"Acme Corp"`                   | Custom metadata             |
| `"features"`     | `"export,api,priority-support"` | Feature list for the user   |

### Setting license variables

**Dashboard:** Open an app → click a license row → Variables

**Developer API:**

```bash theme={null}
# Get current variables for a license
curl https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT/variables \
  -H "Authorization: Bearer af_live_your_key"

# Set variables (replaces all variables)
curl -X PUT https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT/variables \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "pro",
    "maxProjects": 10,
    "customerName": "Acme Corp"
  }'
```

### Reading license variables in the SDK

<CodeGroup>
  ```python Python theme={null}
  if client.login(license_key):
      plan = client.license_variables.get("plan", "basic")

      if plan == "pro":
          enable_pro_features()
      elif plan == "enterprise":
          enable_enterprise_features()
      else:
          enable_basic_features()

      max_projects = int(client.license_variables.get("maxProjects", 3))
  ```

  ```csharp C# theme={null}
  if (client.Login(licenseKey))
  {
      var plan = client.LicenseVariables.GetValueOrDefault("plan", "basic")?.ToString();

      switch (plan)
      {
          case "pro":
              EnableProFeatures();
              break;
          case "enterprise":
              EnableEnterpriseFeatures();
              break;
          default:
              EnableBasicFeatures();
              break;
      }
  }
  ```
</CodeGroup>

***

## Limits

| Limit                     | Value                            |
| ------------------------- | -------------------------------- |
| Max keys per variable set | 50                               |
| Max total size (JSON)     | 4 KB                             |
| Key max length            | 64 characters                    |
| Value types               | String, number, boolean          |
| Nesting                   | Not supported (flat values only) |

These limits apply independently to app variables and license variables.

## How variables are delivered

Variables are included in the signed payload returned by `/auth/validate`. This means:

1. Variables are delivered at login time, not on every heartbeat.
2. To pick up variable changes, the user must re-authenticate (restart the app, or wait for LOCAL mode to re-validate).
3. Variables are covered by the same Ed25519 signature as the rest of the payload; they can't be tampered with in transit.

## Next steps

* [Feature Flags Guide](/guides/feature-flags); Use app variables as a simple feature flag system
* [Tiered Licensing Guide](/guides/tiered-licensing); Implement Basic/Pro/Enterprise tiers with license variables
* [Variables API Reference](/api/variables); Full endpoint documentation