> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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, only `FPJS_INTEGRATION_PATH` is needed.
`FPJS_AGENT_PATH` and `FPJS_RESULT_PATH` related configs can be removed.
## 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:
* Remove `fpjs_agent_path` and `fpjs_result_path` variables.
* Add the new `fpjs_integration_path_escaped` variable.
```terraform main.tf theme={"theme":"github-dark-dimmed"}
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_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][proxy-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][akamai-terraform].
### 1.2 Using Akamai Property Manager API (PAPI)
1. Clone the [Akamai proxy integration repository][proxy-github-repo]:
```bash theme={"theme":"github-dark-dimmed"}
git clone git@github.com:fingerprintjs/akamai-proxy.git
```
2. Install dependencies:
```bash theme={"theme":"github-dark-dimmed"}
pnpm install
```
3. Generate the patch body. Note that `--agent-path` and `--result-path` are no longer needed:
```bash theme={"theme":"github-dark-dimmed"}
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][akamai-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:
```javascript NPM theme={"theme":"github-dark-dimmed"}
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:
```javascript NPM theme={"theme":"github-dark-dimmed"}
import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'; // [!code --]
import * as Fingerprint from '@fingerprint/agent'; // [!code ++]
// [!code --:11]
const fpPromise = FingerprintJS.load({
apiKey: 'PUBLIC_API_KEY',
region: 'us',
scriptUrlPattern: [
'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_AGENT_PATH?apiKey=&version=&loaderVersion=',
FingerprintJS.defaultScriptUrlPattern,
],
endpoint: [
'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_RESULT_PATH?region=us',
FingerprintJS.defaultEndpoint,
],
});
// [!code ++:5]
const fp = Fingerprint.start({
apiKey: 'PUBLIC_API_KEY',
region: 'us',
endpoints: ['https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH?region=us'],
});
```
```javascript CDN theme={"theme":"github-dark-dimmed"}
// [!code --:7]
const url = 'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_AGENT_PATH?apiKey=PUBLIC_API_KEY';
const fpPromise = import(url)
.then(FingerprintJS => FingerprintJS.load({
region: 'us',
endpoint: [
'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_RESULT_PATH?region=us',
FingerprintJS.defaultEndpoint,
],
}));
// [!code ++:6]
const fpPromise =
import('https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/web/v4/PUBLIC_API_KEY?region=us').then(
(Fingerprint) =>
Fingerprint.start({
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][js-agent-migration].
## Step 4: Monitor and finalize
After rollout:
* Monitor proxied traffic and error rate from the [integration status page][fingerprint-integrations] 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**: The `fpjs_agent_path` and `fpjs_result_path` variable blocks should already be removed from Step 1.
* **PAPI**: The updated property rules no longer use `FPJS_AGENT_PATH` and `FPJS_RESULT_PATH`, so no additional cleanup is needed.
[akamai-papi]: /docs/deploy-akamai-proxy-integration-via-papi
[akamai-terraform]: /docs/deploy-akamai-proxy-integration-via-terraform
[fingerprint-integrations]: https://dashboard.fingerprint.com/integrations
[js-agent-migration]: /reference/migrating-from-v3-to-v4
[proxy-github-repo]: https://github.com/fingerprintjs/akamai-proxy
[proxy-latest-release]: https://github.com/fingerprintjs/akamai-proxy/releases/latest