Migrate Akamai integration from API v3 to API v4

Welcome! This guide helps you migrate your Akamai integration from API v3 to API v4.

You will first gather your existing integration details, then upgrade your Akamai property configuration so it can handle both v3 and v4 routes, validate v4 traffic through the proxy before changing production, update your app to JavaScript Agent v4, and finally monitor the rollout and clean up any v3-specific configuration once v3 traffic has fully stopped.

Follow the steps below in order. If you keep v3 working while you validate v4, you can roll forward safely and avoid user impact.

Step 0: Collect Inputs (no changes yet)

You should have:

• Your current integration domain (example: https://metrics.yourwebsite.com)
• Your current proxy secret (FPJS_PROXY_SECRET property sensitive variable)
• Your current v3 integration path variables:
  • FPJS_INTEGRATION_PATH (found in the path match criteria of the Fingerprint rule)
  • FPJS_AGENT_PATH (found in the path match criteria of the Fingerprint > Origin for Agent rule)
  • FPJS_RESULT_PATH (found in the path match criteria of the Fingerprint > Origin for Ingress rule)
• Your public API key
• Your region (example: us, eu, ap)

After migration is complete and your website is fully on agent v4, the client agent only needs FPJS_INTEGRATION_PATH. The Terraform rules template still requires fpjs_agent_path and fpjs_result_path to be defined (see Step 1.1). Keep them set to your real v3 values while v3 clients are still active, and switch them to placeholder values once you retire v3 (see Step 4).

Step 1: Upgrade your Akamai integration

Update the Akamai property configuration to a version that supports JavaScript Agent v4. Choose your deployment method below.

1.1 Using Terraform

1. Update your akamai_property_rules_template variable blocks:

   • Keep fpjs_agent_path and fpjs_result_path set to their current v3 path values until no clients use v3.
   • Add the new fpjs_integration_path_escaped variable.
   main.tf

   data "akamai_property_rules_template" "rules" {
         template_file = "/rules/main.json"
         variables {
           name  = "fpjs_integration_path"
           value = "FPJS_INTEGRATION_PATH"
           type = "string"
         }
         variables {
           name  = "fpjs_integration_path_escaped"
           value = "YOUR_INTEGRATION_PATH_ESCAPED" # same as FPJS_INTEGRATION_PATH but with / escaped as \\/ and . escaped as \.
           type = "string"
         }
         variables {
           name  = "fpjs_agent_path"
           value = "FPJS_AGENT_PATH" # Keep this v3 value until no clients use v3.
           type = "string"
         }
         variables {
           name  = "fpjs_result_path"
           value = "FPJS_RESULT_PATH" # keep your existing v3 value until no clients use v3 (see Step 4)
           type = "string"
         }
         variables {
           name  = "fpjs_proxy_secret"
           value = "FPJS_PROXY_SECRET"
           type = "string"
         }
   }
   

2. Download the latest terraform-fingerprint-property-rules.json and terraform-fingerprint-property-variables.json files from the latest release and replace the existing ones in your rules directory.

3. Run terraform plan to review your changes.

4. Run terraform apply.

For full details, see Deploy Akamai proxy integration using Terraform.

1.2 Using Akamai Property Manager API (PAPI)

1. Clone the Akamai proxy integration repository:

   git clone [e-mail]:fingerprintjs/akamai-proxy.git
   

2. Install dependencies:

   pnpm install
   

3. Generate the patch body. Note that --agent-path and --result-path are no longer needed:

   pnpm build --type patchBody \
       --integration-path "FPJS_INTEGRATION_PATH" \
       --proxy-secret "FPJS_PROXY_SECRET"
   

4. Follow the PAPI deployment steps (clone property version, remove existing Fingerprint artifacts, patch, activate) as described in Deploy Akamai proxy integration using PAPI.

1.3 Verify

Acceptance criteria:

• The integration can still serve v3 agent download and identification requests.
• The integration can also route v4 requests, for example requests under /FPJS_INTEGRATION_PATH/web/v4/....

Verification ideas:

• Open https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/status and confirm the integration is healthy.

• Confirm your existing (v3) production client still works and can identify.

• Validate v4 routing through the proxy with a quick test:

  NPM

  import * as Fingerprint from '@fingerprint/agent';
  
  const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      region: 'us',
      endpoints: ['https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH?region=us'],
  });
  
  fp.get().then((result) => console.log(result));
  

Step 2: Validate v4 routing before changing your production client

Before flipping your app, test v4 through the proxy.

Options:

• Use a staging site / feature flag to load agent v4.
• Temporarily run agent v4 in a dev environment.

What to check:

• The agent script loads through the proxy (no ad blocker or CDN errors)
  • You may use browser dev tools’ network tab to confirm the script is loaded from the proxy.
• Identification requests go through the proxy (not directly to Fingerprint default endpoints)
• Results are returned successfully

Step 3: Update your application to JavaScript Agent v4

Update your website to load and initialize agent v4 using your proxy base URL. Replace the placeholders with your values:

NPM

import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'; 
import * as Fingerprint from '@fingerprint/agent'; 

const fpPromise = FingerprintJS.load({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    scriptUrlPattern: [
        'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_AGENT_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>',
        FingerprintJS.defaultScriptUrlPattern,
    ],
    endpoint: [
        'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_RESULT_PATH?region=us',
        FingerprintJS.defaultEndpoint,
    ],
});

const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    endpoints: ['https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH?region=us'],
});

To learn more about JavaScript Agent v4 changes, see the JavaScript Agent v3 to v4 migration guide.

Step 4: Monitor and finalize

After rollout:

• Monitor proxied traffic and error rate from the integration status page in the Fingerprint Dashboard.
• Confirm the majority of traffic is using v4 paths.

Optional cleanup (later):

• If you introduced any temporary parallel paths for testing, remove them.
• When you are confident no clients use v3, you can remove v3-specific configuration:
  • Terraform: Keep the fpjs_agent_path and fpjs_result_path variable blocks set to placeholder values from Step 1 — Terraform still requires them even though they’re no longer used for routing.
  • PAPI: The updated property rules no longer use FPJS_AGENT_PATH and FPJS_RESULT_PATH, so no additional cleanup is needed.