Deploy Akamai Integration using Property Manager API

📘

Before you start: Read the general Akamai guide

This document only covers deploying the Fingerprint Akamai proxy integration using the Akamai Property Manager API (PAPI). It assumes you have already read the general Akamai guide and completed the following steps:

• Step 1: You have issued a proxy secret in the Fingerprint Dashboard (FPJS_PROXY_SECRET).
• Step 2: You have defined the path variables for the integration (FPJS_INTEGRATION_PATH, FPJS_AGENT_PATH, FPJS_RESULT_PATH)

If you want to use Terraform instead of PAPI to install the integration, see Deploy Akamai proxy integration using Terraform.

Prerequisites

This deployment guide assumes you already have a working Akamai property and are familiar with the Akamai Control Panel. It uses Postman to make the HTTP requests, but feel free to adjust the instructions to use your preferred HTTP client.

Step 3: Authenticate with EdgeGrid

1. Follow the Akamai documentation to Create EdgeGrid authentication credentials. You should end up downloading a credentials text file containing the values used below.
2. Inside Postman, use the values from the credentials file to configure the EdgeGrid authentication for your HTTP requests:
   1. Go to the Authorization tab.
   2. Set the Type to Akamai EdgeGrid.
   3. Set Access Token, Client Token, and Client Secret to the values from the credentials file.
   4. Set the base URL of the request according to the host value from the credentials file, e.g. https://akab-xxxxxxxx.luna.akamaiapis.net.

Note: If your HTTP client does not support EdgeGrid authentication, you can use the same values to manually create the EdgeGrid authentication header. See the EdgeGrid Protocol Specification for more details.

Step 4: Clone the Akamai integration repository

1. Clone the repository:

git clone [email protected]:fingerprintjs/fingerprint-pro-akamai-proxy-integration.git

2. Install dependencies using PNPM:

pnpm install

Step 5: Generate Patch Body

Use the build npm command to generate the integration's property rules for your Akamai property. Use the values from previous steps to configure the command:

• integration-path, agent-path, and result-path should be short, unique strings — avoid using fpjs or other recognizable words.
• proxy-secret can be created in Fingerprint Dashboard → API Keys.

pnpm build --type patchBody \
  --integration-path <FPJS_INTEGRATION_PATH> \
  --agent-path <FPJS_AGENT_PATH> \
  --result-path <FPJS_RESULT> \
  --proxy-secret <FPJS_PROXY_SECRET>

The output will be saved to dist/patch-body/body.json.

Step 6: Deploy using Property Manager API

Use the following sequence of PAPI requests to collect the necessary data and deploy the integration.

• baseURL is created from the host value from the credentials file, e.g. https://akab-xxxxxxxx.luna.akamaiapis.net.
• Authenticate all requests using EdgeGrid credentials as described in Step 3.

Step 6.1: Get your Contract ID

GET https://{baseURL}/papi/v1/contracts

Sample Response:

{
  "accountId": "act_A-CCT5678",
  "contracts": {
    "items": [
      {
        "contractId": "ctr_C-0N7RAC71",
        "contractTypeName": "DIRECT_CUSTOMER"
      }
    ]
  }
}

Save the contractId to use in later requests.

Step 6.2: Get your Group ID

GET https://{baseURL}/papi/v1/groups

Sample Response:

{
  "accountId": "act_A-CCT3456",
  "accountName": "Internet Company",
  "groups": {
    "items": [
      {
        "contractIds": ["ctr_C-0N7RAC71"],
        "groupId": "grp_32145",
        "groupName": "Example.com-1-1TJZH5"
      }
    ]
  }
}

Save the groupId associated with your contractId to use in later requests.

Step 6.3: Get your Property ID

GET https://{baseURL}/papi/v1/properties?contractId=ctr_C-0N7RAC71&groupId=grp_32145

Sample Response:

{
  "properties": {
    "items": [
      {
        "accountId": "act_A-CCT9012",
        "assetId": "aid_101",
        "contractId": "ctr_C-0N7RAC7",
        "groupId": "grp_54321",
        "latestVersion": 2,
        "propertyId": "prp_175780",
        "propertyName": "example.com"
      }
    ]
  }
}

Find the property you want to deploy the integration to. Save its propertyId and latestVersion to use in later requests.

Step 6.4: Get your Property Versions (optional but recommended)

To make changes to your property, you first need to clone one of its versions. To decide which version to clone, you can get the list of all versions for your property.

GET https://{baseURL}/papi/v1/properties/{propertyId}/versions?contractId=ctr_C-0N7RAC71&groupId=grp_32145

Sample Response:

{
  "accountId": "act_A-CCT7890",
  "assetId": "aid_101",
  "contractId": "ctr_C-0N7RAC71",
  "groupId": "grp_54321",
  "propertyId": "prp_173136",
  "propertyName": "981.catalog.jsmith.net",
  "versions": {
    "items": [
      {
        "propertyVersion": 2,
        "note": "updated caching",
        "productionStatus": "INACTIVE",
        "stagingStatus": "ACTIVE"
      },
      {
        "propertyVersion": 1,
        "note": "initial version",
        "productionStatus": "ACTIVE",
        "stagingStatus": "INACTIVE"
      }
    ]
  }
}

Step 6.5: Clone the current version of your property

POST https://{baseURL}/papi/v1/properties/{propertyId}/versions?contractId=ctr_C-0N7RAC71&groupId=grp_32145

Request Body:

{
  "createFromVersion": <Your property version to clone here>
}

Sample Response:

{
  "versionLink": "/papi/v0/properties/prp_173136/versions/2?contractId=ctr_C-0N7RAC71&groupId=grp_15225"
}

Step 6.6: Remove existing Fingerprint artifacts (if needed)

If your Akamai property already has the Fingerprint proxy integration installed, manually remove the Fingerprint artifacts before updating the integration. Otherwise, some artifacts will be duplicated and the integration will not work.

1. Navigate to Akamai Control Center → Properties.
2. Find the cloned property version.
3. Click Edit to begin editing rules.
4. Navigate to the Variables section and remove all variables that start with PMUSER_FPJS_.
5. Scroll to the bottom of the rule tree and delete the rule named Fingerprint.
6. Click Save to confirm the cleanup.

Step 6.7: Patch the new version with Fingerprint integration rules

Finally, send a PATCH request to update your property's rule tree with the Fingerprint integration rules:

PATCH https://{baseURL}/papi/v1/properties/{propertyId}/versions/{newVersion}/rules?contractId=ctr_C-0N7RAC71&groupId=grp_32145

• Request body: Copy-paste the content of the dist/patch-body/body.json file you created in Step 5.
• Content-type: header application/json-patch+json

Sample Response:

{
  "accountId": "act_A-CCT1234",
  "contractId": "ctr_K-0N7RAK71",
  "etag": "a9dfe78cf93090516bde891d009eaf57",
  "groupId": "grp_12345",
  "propertyId": "prp_173136",
  "propertyName": "mytestproperty.com",
  "propertyVersion": 3,
  "ruleFormat": "v2015-08-08",
  "rules": {
    "name": "default",
    "behaviors": [],
    "children": []
  }
}

Step 6.8: Activate the Patched Version

POST https://{baseURL}/papi/v1/properties/{propertyId}/activations?contractId=ctr_C-0N7RAC71&groupId=grp_32145

• Request body:
  JSON

  {
    "propertyVersion": <Your cloned property version to activate>,
    "network": "PRODUCTION",
    "notifyEmails": ["<your email address to notify about activation status>"],
    "acknowledgeAllWarnings": true,
    "activationType": "ACTIVATE"
  }

Sample Response:

{
  "activationLink": "/papi/v0/properties/prp_173136/activations/atv_67037?contractId=ctr_K-0N7RAK7&groupId=grp_15225"
}

⚠️

This will directly activate the version in PRODUCTION. If you want to deploy to staging first, change the network value to STAGING.

Troubleshooting API requests

If you encounter an error, check the following:

Step 7: Configure the Fingerprint client agent

Please see the main Akamai proxy integration guide to Configure the client agent on your website or mobile application.