jwrosewell · Nov 11, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -125,7 +125,7 @@ java -cp examples/ip-intelligence/console/target/ip-intelligence-java-examples.c
 ```
 
 The example downloads the Lite file first when it is not there. In place of
-the argument, the `51DEGREES_IPI_PATH` environment variable or system property
+the argument, the `_51DEGREES_IPI_PATH` environment variable or system property
 can give the absolute path of a data file that is already there.
 
 On Java 24 or later, add `--enable-native-access=ALL-UNNAMED` before the class
@@ -183,7 +183,7 @@ java -cp examples/device-detection/console/target/device-detection-java-examples
 
 It prints the same `Input values:` and `Results:` blocks as the on-premise
 example. The IP Intelligence cloud examples read their key from
-`51DEGREES_RESOURCE_KEY` first and `TestResourceKey` second, and
+`_51DEGREES_RESOURCE_KEY` first and `TestResourceKey` second, and
 `examples/ip-intelligence/README.md` gives the keys to create for them.
 
 ### Pitfalls

diff --git a/ci/run-integration-tests.ps1 b/ci/run-integration-tests.ps1
@@ -162,7 +162,7 @@ if (-not $TestResourceKey) {
             Module = 'web/getting-started.onprem'
             Port = 8098
             ExampleEnv = @{
-                '51DEGREES_DD_PATH' = (Resolve-Path "$RepoName/cxx/data/device-detection/TAC-HashV41.hash").Path
+                '_51DEGREES_DD_PATH' = (Resolve-Path "$RepoName/cxx/data/device-detection/TAC-HashV41.hash").Path
             }
         }
     )

diff --git a/examples/device-detection/README.md b/examples/device-detection/README.md
@@ -122,7 +122,7 @@ case the example runs until the process is stopped:
 PORT=8100 java -jar ./web/getting-started.onprem/target/device-detection-java-examples.web.getting-started.onprem-4.4.20-jar-with-dependencies.jar
 ```
 
-The on-premise web example takes its data file from the `51DEGREES_DD_PATH`
+The on-premise web example takes its data file from the `_51DEGREES_DD_PATH`
 environment variable, then from `TestDataFile`, and otherwise uses the free Lite file
 in `cxx/data/device-detection`, which it downloads before the server starts if it is
 missing.

diff --git a/...d.onprem/src/main/java/fiftyone/devicedetection/examples/web/GettingStartedWebOnPrem.java b/...d.onprem/src/main/java/fiftyone/devicedetection/examples/web/GettingStartedWebOnPrem.java
@@ -48,7 +48,7 @@
  * <p>
  * The configuration file for the pipeline is at src/main/webapp/WEB-INF/51Degrees-OnPrem.xml
  * <p>
- * The data file is taken from the 51DEGREES_DD_PATH environment variable, then
+ * The data file is taken from the _51DEGREES_DD_PATH environment variable, then
  * from TestDataFile (an environment variable or system property), and otherwise
  * the free Lite file in cxx/data/device-detection is used, which is downloaded
  * before the server starts if it is missing.

diff --git a/.../device-detection/web/getting-started.onprem/src/main/webapp/WEB-INF/51Degrees-OnPrem.xml b/.../device-detection/web/getting-started.onprem/src/main/webapp/WEB-INF/51Degrees-OnPrem.xml
@@ -28,11 +28,11 @@
                 <AutoUpdate>false</AutoUpdate>
                 <CreateTempDataCopy>false</CreateTempDataCopy>
                 <!--
-                The data file is taken from the 51DEGREES_DD_PATH environment
+                The data file is taken from the _51DEGREES_DD_PATH environment
                 variable, then from TestDataFile (an environment variable or
                 system property), and otherwise the free Lite file is used.
                 -->
-                <DataFile>${51DEGREES_DD_PATH:-${TestDataFile:-cxx/data/device-detection/51Degrees-LiteV4.1.hash}}</DataFile>
+                <DataFile>${_51DEGREES_DD_PATH:-${TestDataFile:-cxx/data/device-detection/51Degrees-LiteV4.1.hash}}</DataFile>
                 <PerformanceProfile>LowMemory</PerformanceProfile>
             </BuildParameters>
             <BuilderName>DeviceDetectionHashEngine</BuilderName>

diff --git a/....onprem/src/test/java/fiftyone/devicedetection/examples/web/OnPremDataFileOptionTest.java b/....onprem/src/test/java/fiftyone/devicedetection/examples/web/OnPremDataFileOptionTest.java
@@ -35,12 +35,12 @@
 
 /**
  * Checks the order in which the on-premise web example picks its data file,
- * being 51DEGREES_DD_PATH first, then TestDataFile, then the Lite file.
+ * being _51DEGREES_DD_PATH first, then TestDataFile, then the Lite file.
  * System properties stand in for the environment variables, because the
  * lookup reads either and a test cannot set an environment variable.
  */
 public class OnPremDataFileOptionTest {
-    private static final String DD_PATH = "51DEGREES_DD_PATH";
+    private static final String DD_PATH = "_51DEGREES_DD_PATH";
     private static final String TEST_DATA_FILE = "TestDataFile";
     private static final String LITE =
             "cxx/data/device-detection/51Degrees-LiteV4.1.hash";

diff --git a/examples/ip-intelligence/README.md b/examples/ip-intelligence/README.md
@@ -28,7 +28,7 @@ gives a link to ask for a copy. The Compare, Metrics and Suspicious examples nee
 properties, so with a free data file they say which they need and stop.
 [Contact us](https://51degrees.com/contact-us?utm_source=github&utm_medium=readme&utm_campaign=51degrees-java&utm_content=readme.md&utm_term=enterprise-data-file) for a copy of
 the Enterprise data file. To use it, place it in `cxx/data/ip-intelligence` and pass its path
-as the first argument, or set the `51DEGREES_IPI_PATH` environment variable or system
+as the first argument, or set the `_51DEGREES_IPI_PATH` environment variable or system
 property to its path.
 
 The Enterprise data file is over 6 GB, and the MaxPerformance profile loads all of it into
@@ -61,7 +61,7 @@ Compare and Suspicious examples with the Enterprise data file are skipped.
 
 The examples locate the data file in the following order:
 
-1. The `51DEGREES_IPI_PATH` environment variable or system property, which can
+1. The `_51DEGREES_IPI_PATH` environment variable or system property, which can
    be set to an explicit path to the data file. It is used in place of any
    file named without a full path.
 2. The path given as the first argument, or the free file the example uses
@@ -104,7 +104,7 @@ environment variable or system property.
 | MetadataCloud            | How to access the meta-data that relates to the properties available from the cloud IP intelligence service.                                 |
 
 Cloud examples need a resource key. The key is read from the
-`51DEGREES_RESOURCE_KEY` environment variable or system property first. The
+`_51DEGREES_RESOURCE_KEY` environment variable or system property first. The
 legacy `TestResourceKey` name is still supported and is checked second.
 
 The cloud property tiers changed in May 2026. The examples and this

diff --git a/...nce/console/src/main/java/fiftyone/ipintelligence/examples/console/OfflineProcessing.java b/...nce/console/src/main/java/fiftyone/ipintelligence/examples/console/OfflineProcessing.java
@@ -184,7 +184,7 @@ public static void run(String dataFile, InputStream is, OutputStream os) throws
                 // We use the low memory profile, which reads the data file
                 // from disk as it is needed, because this example may be
                 // given the Enterprise data file, which is over 6 GB, through
-                // its first argument or 51DEGREES_IPI_PATH. MaxPerformance
+                // its first argument or _51DEGREES_IPI_PATH. MaxPerformance
                 // loads the whole data file into memory, which makes each
                 // lookup faster where there is memory to hold it.
                 .setPerformanceProfile(Constants.PerformanceProfiles.LowMemory)

diff --git a/...lligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/DataFileHelper.java b/...lligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/DataFileHelper.java
@@ -133,7 +133,7 @@ public static String findAvailableDataFile(String... candidates) {
      * hold an explicit path to the IP Intelligence data file. This name is
      * checked first, before any search of the project space.
      */
-    public static final String IPI_PATH_ENV_VAR = "51DEGREES_IPI_PATH";
+    public static final String IPI_PATH_ENV_VAR = "_51DEGREES_IPI_PATH";
 
 public static class DatafileInfo {
         FiftyOneDataFile fileInfo;

diff --git a/...-intelligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/KeyHelper.java b/...-intelligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/KeyHelper.java
@@ -30,12 +30,6 @@
 import java.util.function.Function;
 
 public class KeyHelper {
-    /**
-     * Aligned name of the environment variable or system property which may
-     * hold the resource key. This name is checked first, before the legacy
-     * {@link #TEST_RESOURCE_KEY} name.
-     */
-    public static final String RESOURCE_KEY_ENV_VAR = "51DEGREES_RESOURCE_KEY";
     public static final String TEST_RESOURCE_KEY = "TestResourceKey";
     static Logger logger = LoggerFactory.getLogger(KeyHelper.class);
 
@@ -63,8 +57,8 @@ public class KeyHelper {
      */
     public static String requireTestResourceKey(String asksFor,
                                                 String... products) {
-        return requireResourceKey(KeyHelper::readKey, Arrays.asList(
-            RESOURCE_KEY_ENV_VAR, TEST_RESOURCE_KEY), asksFor, products);
+        return requireResourceKey(KeyHelper::readKey,
+            Collections.singletonList(TEST_RESOURCE_KEY), asksFor, products);
     }
 
     static String requireResourceKey(Function<String, String> read,
@@ -148,17 +142,18 @@ public static String getOrSetTestResourceKey(String value) {
     }
     /**
      * Obtain a resource key from the passed argument,
-     * from environment variable or from a property. The aligned
-     * {@link #RESOURCE_KEY_ENV_VAR} name is checked first, then the
+     * from environment variable or from a property. The first of
+     * {@link #SHARED_RESOURCE_KEY_NAMES} is checked first, then the
      * passed variable name. Store as System Property under the
      * passed variable name.
      */
     public static String getOrSetResourceKey(String value, String variableName,
                                              String errorMessage,
                                              boolean shouldThrow) {
+        String alignedName = SHARED_RESOURCE_KEY_NAMES.get(0);
         if (Objects.isNull(value)) {
             // check the aligned name first, then the legacy name
-            value = KeyUtils.getNamedKey(RESOURCE_KEY_ENV_VAR);
+            value = KeyUtils.getNamedKey(alignedName);
             if (Objects.isNull(value)) {
                 value = KeyUtils.getNamedKey(variableName);
             }
@@ -170,7 +165,7 @@ public static String getOrSetResourceKey(String value, String variableName,
                     "runnable example,\n - as an Environment Variable named \"\u001B[36m{}\u001B[0m\"," +
                     "\n - as a System Property named \"\u001B[36m{}\u001B[0m\" " +
                     "(the legacy name \"\u001B[36m{}\u001B[0m\" is also still accepted).",
-                    RESOURCE_KEY_ENV_VAR, RESOURCE_KEY_ENV_VAR, variableName);
+                    alignedName, alignedName, variableName);
             logger.error(errorMessage);
             if (shouldThrow) {
                 throw new IllegalStateException("\"" + value + "\" is not a valid resource key");

diff --git a/...elligence/shared/src/test/java/fiftyone/ipintelligence/examples/shared/KeyHelperTest.java b/...elligence/shared/src/test/java/fiftyone/ipintelligence/examples/shared/KeyHelperTest.java
@@ -24,7 +24,7 @@
 
 import org.junit.Test;
 
-import java.util.Arrays;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -44,8 +44,8 @@ public class KeyHelperTest {
     /**
      * The names getOrSetTestResourceKey reads, in its order.
      */
-    private static final List<String> EXAMPLE_NAMES = Arrays.asList(
-        KeyHelper.RESOURCE_KEY_ENV_VAR, KeyHelper.TEST_RESOURCE_KEY);
+    private static final List<String> EXAMPLE_NAMES =
+        Collections.singletonList(KeyHelper.TEST_RESOURCE_KEY);
 
     /**
      * With no key anywhere, the lookup logs that there is none and stores
@@ -88,8 +88,8 @@ public void requireResourceKey_NoKey_FailsNamingEveryName() {
         assertEquals("This test calls the live 51Degrees cloud service, so " +
                 "it needs a resource key and there is nothing to fall back " +
                 "on. None of _51DEGREES_RESOURCE_KEY, " +
-                "_51DEGREES_RESOURCE_KEY_BESPOKE, 51DEGREES_RESOURCE_KEY, " +
-                "TestResourceKey is set, as an environment variable or as a " +
+                "_51DEGREES_RESOURCE_KEY_BESPOKE, TestResourceKey is set, " +
+                "as an environment variable or as a " +
                 "system property, tried in that order. The key has to carry " +
                 "the ip and device products, because the test asks the " +
                 "service for the network and location of an IP address, and " +
@@ -118,11 +118,11 @@ public void requireResourceKey_FirstValidNameWins() {
     @Test
     public void requireResourceKey_ExampleNamesInTheirOrder() {
         Map<String, String> values = new HashMap<>();
-        values.put(KeyHelper.RESOURCE_KEY_ENV_VAR, KEY_A);
+        values.put("_51DEGREES_RESOURCE_KEY", KEY_A);
         values.put(KeyHelper.TEST_RESOURCE_KEY, KEY_B);
         assertEquals(KEY_A, KeyHelper.requireResourceKey(values::get,
             EXAMPLE_NAMES, "every IP Intelligence property", "ip"));
-        values.remove(KeyHelper.RESOURCE_KEY_ENV_VAR);
+        values.remove("_51DEGREES_RESOURCE_KEY");
         assertEquals(KEY_B, KeyHelper.requireResourceKey(values::get,
             EXAMPLE_NAMES, "every IP Intelligence property", "ip"));
     }

diff --git a/ip-intelligence/README.md b/ip-intelligence/README.md
@@ -36,7 +36,7 @@ data file.
 The free 'Lite' and Asn data files come from the [data](https://github.com/51Degrees/data) repository, which is the `cxx/data` folder of this repository. Run `cxx/data/get-data-files.sh ip-intelligence` from the root of this repository to download them, or `cxx\data\get-data-files.ps1 ip-intelligence` in PowerShell on Windows. Otherwise [contact us](https://51degrees.com/contact-us?utm_source=github&utm_medium=readme&utm_campaign=51degrees-java&utm_content=readme.md&utm_term=on-premise) to obtain an 'Enterprise' data file.
 
 For tests, the data file can be supplied explicitly by setting the
-`51DEGREES_IPI_PATH` environment variable or system property to the path of
+`_51DEGREES_IPI_PATH` environment variable or system property to the path of
 the .ipi file. When it is not set, the project space is searched for the
 expected file name, with the free 'Lite' file expected in
 `cxx/data/ip-intelligence`.
@@ -113,7 +113,7 @@ You will need [resource keys](https://51degrees.com/documentation/_services__clo
 
 The tests look for a resource key in the following order:
 
-1. The aligned `51DEGREES_RESOURCE_KEY` name, set as an environment variable
+1. The aligned `_51DEGREES_RESOURCE_KEY` name, set as an environment variable
    or as a system property.
 2. The legacy `TestResourceKey` name, which is still supported and is checked
    after the aligned name.

diff --git a/...telligence.shared/src/main/java/fiftyone/ipintelligence/shared/testhelpers/FileUtils.java b/...telligence.shared/src/main/java/fiftyone/ipintelligence/shared/testhelpers/FileUtils.java
@@ -43,7 +43,7 @@ public class FileUtils {
      * supply an explicit path to the IPI data file. When set and the file
      * exists it is used in preference to searching the project space.
      */
-    public static final String IPI_PATH_ENV_VAR = "51DEGREES_IPI_PATH";
+    public static final String IPI_PATH_ENV_VAR = "_51DEGREES_IPI_PATH";
 
     public static final String ENTERPRISE_IPI_DATA_FILE_NAME = "Enterprise-IpIntelligenceV41.ipi";
 

diff --git a/...ntelligence.shared/src/main/java/fiftyone/ipintelligence/shared/testhelpers/KeyUtils.java b/...ntelligence.shared/src/main/java/fiftyone/ipintelligence/shared/testhelpers/KeyUtils.java
@@ -33,7 +33,7 @@ public class KeyUtils {
      * Name of the aligned environment variable or system property which
      * supplies the resource key. This name is checked before any legacy name.
      */
-    public static final String RESOURCE_KEY_ENV_VAR = "51DEGREES_RESOURCE_KEY";
+    public static final String RESOURCE_KEY_ENV_VAR = "_51DEGREES_RESOURCE_KEY";
 
     /**
      * Obtain a resource key from an environment variable or a system property.

diff --git a/.../src/test/java/fiftyone/ipintelligence/translation/CountryTranslationIntegrationTest.java b/.../src/test/java/fiftyone/ipintelligence/translation/CountryTranslationIntegrationTest.java
@@ -50,7 +50,7 @@
  * complete, localized, ordered country dropdown is produced.
  * <p>
  * The data file is resolved from the {@code TestDataFile} system property, the
- * {@code 51DEGREES_IPI_PATH} environment variable, or a few well known
+ * {@code _51DEGREES_IPI_PATH} environment variable, or a few well known
  * locations, and the test is skipped if none is found.
  * <p>
  * The IP Intelligence element data key has differed between engine versions
@@ -66,7 +66,7 @@ public class CountryTranslationIntegrationTest {
     private static String resolveDataFile() {
         String[] candidates = {
             System.getProperty("TestDataFile"),
-            System.getenv("51DEGREES_IPI_PATH"),
+            System.getenv("_51DEGREES_IPI_PATH"),
             "51Degrees-IPIV4EnterpriseIpiV41.ipi",
             "../51Degrees-IPIV4EnterpriseIpiV41.ipi",
             "../../51Degrees-IPIV4EnterpriseIpiV41.ipi",