Guide

Manage a distributed key-value store for EdgeWorkers

Control EdgeKV database functions outside EdgeWorkers JavaScript code by creating new namespaces, updating data, deleting data, and managing access tokens.

👍

Tip

See the Akamai Edge Computing demo for EdgeWorker use cases with and without EdgeKV.

What you'll do

Create an EdgeKV database and add it to the EdgeWorkers code bundle.

What you need

To use an EdgeKV database, you need:

  • An EdgeWorker.
  • A property from the Property Manager (PAPI) API.

❗️

Important

  • Because the setup for EdgeWorkers affects your company's billing plan, the integration for EdgeWorkers requires admin access to your Akamai account.
  • Before setting up the integration, get familiar with the product limitations for EdgeWorkers and EdgeKV.

1. Create an EdgeWorker

Use the New-EdgeWorker operation to create a new EdgeWorker ID within your group ID, assigning a resource tier.

For a list of available resource tiers on your contract, run the Get-EdgeWorkerResourceTier operation.

New-EdgeWorker -EdgeWorkerName 'my-edgeworker' -GroupID 12345 -ResourceTierID 200

edgeWorkerId     : 54321
name             : my-edgeworker
accountId        : A-CCT1234
groupId          : 12345
resourceTierId   : 200
createdBy        : jsmith
createdTime      : 2/9/2026 1:10:09 PM
lastModifiedBy   : jsmith
lastModifiedTime : 2/9/2026 1:10:09 PM

2. Initialize an EdgeKV database

By default, EdgeWorkers are stateless and relay responses without storing any information. Adding an optional EdgeKV database makes your EdgeWorker instance stateful. This lets you save information about interactions with your site.

❗️

Important

You are responsible for maintaining control over the data hosted through this service and for the appropriate use of the data returned.

While EdgeKV encrypts data at rest and in transit, it does not protect against unauthorized disclosure or support the storage of sensitive information. Choosing to store sensitive information would be a serious business or compliance issue.

If you use EdgeKV for the first time, you need to initialize it on your account with the Initialize-EdgeKV operation. You need to do this only once. This adds the default EdgeKV namespace to Akamai's staging and production networks and creates a new dedicated CP code for you to track your EdgeKV usage.

Initialize-EdgeKV

cpcode  accountStatus productionStatus stagingStatus
------  ------------- ---------------- -------------
12345   INITIALIZED   INITIALIZED      INITIALIZED

To check the EdgeKV initialization status, run the Get-EdgeKVInitializationStatus operation.

Get-EdgeKVInitializationStatus

cpcode           : 12345
accountStatus    : INITIALIZED
productionStatus : INITIALIZED
stagingStatus    : INITIALIZED
dataAccessPolicy : @{restrictDataAccess=True; allowNamespacePolicyOverride=False}

After initializing EdgeKV, you can change the default data access policy on your account with the Set-EdgeKVDefaultAccessPolicy operation. The updated policy applies only to new namespaces created after the change is made. Any namespaces that were created before the update retain their original policy.

3. Create an EdgeKV namespace

An EdgeKV namespace is a logical container that holds your key-value data. It lets you separate different sets of data and define settings, like access control, geolocation, and retention period for a specific namespace.

Beyond the automatically created default namespace, you can add additional namespaces to your EdgeKV database by running the New-EdgeKVNamespace operation.

New-EdgeKVNamespace -Name 'marketing' -RetentionInSeconds 86400 -GeoLocation 'US' -Network 'STAGING' -GroupID 12345

retentionInSeconds : 86400
geoLocation        : US
namespaceStatus    : READY
groupId            : 12345
dataAccessPolicy   : @{restrictDataAccess=True; policyType=inherited}
namespace          : marketing

Things to take into account when running this operation:

  • Accepted values for the -RetentionInSeconds parameter are between 86400 for one day and 315360000 for 10 years. A value of 0 means that data is retained indefinitely.
  • You can't modify the geolocation for your namespace once you set it with this operation.
  • Currently, only a valid geolocation for the STAGING network is US.
  • You can only configure the -RestrictDataAccess parameter if the default data access policy has allowNamespacePolicyOverride set to true.
  • A value of 0 in the -GroupID parameter makes the namespace available to all groups on the account with access to EdgeKV capabilities. If you want to restrict the namespace to a specific Akamai access group, specify the group ID. This value must be the same for both the staging and production instances of a namespace.
  • When you assign an access group to a namespace, the assignment is network-environment specific. You can choose to add an access group that allows full access to a namespace on staging, while adding another access group that restricts access to production namespaces.

As a best practice, you should associate any EdgeWorker IDs that you create with the same group ID as the namespace the EdgeWorker uses.

Manage an EdgeKV namespace

Update a namespace

With the Set-EdgeKVNamespace operation, you can update the retention period for any existing namespace other than the default namespace. It can take up to five minutes for a new retention policy to apply.

You can't update the namespace's name. The -Name and -NamespaceID parameters need to match.

You can run this operation using one of these methods:

  • Update the namespace's retention policy using individual parameters.

    Set-EdgeKVNamespace -Network 'STAGING' -NamespaceID 'marketing' -Name 'marketing' -RetentionInSeconds '15724800' -GroupID 12345

    retentionInSeconds : 15724800
geoLocation        : US
namespaceStatus    : READY
groupId            : 12345
dataAccessPolicy   : @{restrictDataAccess=True; policyType=inherited}
namespace          : marketing

  • Update the namespace's retention policy in a variable as a hashtable, PSCustomObject, or JSON string, and then pipe the variable to the Set-EdgeKVNamespace command or pass the variable in the -Body parameter.

    $MyUpdatedEdgeKV = @{
  retentionInSeconds = 15724800
  groupId = 12345
  namespace = 'marketing'
}

$MyUpdatedEdgeKV | Set-EdgeKVNamespace -Network 'STAGING' -NamespaceID 'marketing'

    $MyUpdatedEdgeKV = '{
  "retentionInSeconds": 15724800,
  "groupId": 12345,
  "namespace": "marketing"
}'

$MyUpdatedEdgeKV | Set-EdgeKVNamespace -Network 'STAGING' -NamespaceID 'marketing'

If you try to change the Akamai access group used to authorize permission to the namespace with this operation, you get an error. Run the Move-EdgeKVNamespace operation to change the access group.

Reauthorize a namespace

You can assign your existing namespace to a different Akamai access group with the Move-EdgeKVNamespace operation. It can take up to five minutes for a new group assignment to apply.

A value of 0 in the -GroupID parameter makes the namespace available to all groups on the account with access to EdgeKV capabilities. If you want to restrict the namespace to a specific Akamai access group, specify the group ID. This value must be the same for both the staging and production instances of a namespace.

Move-EdgeKVNamespace -NamespaceID 'marketing' -GroupID 98765

groupId
-------
  98765

The output returns the updated Akamai access group ID for the namespace.

If you try to run the Get-EdgeKVNamespace operation before the group has been updated globally, the stale data may be returned until the group assignment is complete.

Delete a namespace

If you're about to reach the limit on the number of namespaces per account, you can remove the namespace and all its content with the Remove-EdgeKVNamespace command.

Use caution when deleting a namespace. This operation is permanent and irreversible once completed.

Remove-EdgeKVNamespace -Network 'STAGING' -NamespaceID 'marketing'

scheduledDeleteTime
-------------------
2/13/2026 12:56:14 PM

The output returns the scheduled time when the namespace gets deleted. The namespace delete occurs three days from the time when you scheduled the delete. When you schedule a namespace delete it immediately disables data read and write operations within the namespace.

You can also reschedule the time of the namespace delete by running the Set-EdgeKVNamespaceDelete operation. To do that:

  1. Save you current namespace delete time from the Get-EdgeKVNamespaceDelete operation in a variable and update the scheduledDeleteTime attribute with a new time.

    The scheduledDeleteTime can't exceed 259200 seconds.

  2. Then pipe the updated attribute back to the Set-EdgeKVNamespaceDelete command with the required network type and namespace ID to make your changes effective.

    $MyDeleteSchedule = Get-EdgeKVNamespaceDelete -Network 'STAGING' -NamespaceID 'marketing'

# Specify a new date and pipe it to the Set command
$MyDeleteSchedule.scheduledDeleteTime = '2026-02-12T12:55:10Z'
$MyDeleteSchedule.scheduledDeleteTime | Set-EdgeKVNamespaceDelete -Network 'STAGING' -NamespaceID 'marketing'

# Or use the AddDays() method to change the deletion day and pipe it to the Set command
$MyDeleteSchedule.scheduledDeleteTime.AddDays(-1) | Set-EdgeKVNamespaceDelete -Network 'STAGING' -NamespaceID 'marketing'

    scheduledDeleteTime
-------------------
2/12/2026 12:55:10 PM

Additionally, you have the option of cancelling the previously scheduled namespace delete with the Restore-EdgeKVNamespace operation. You need to cancel a namespace delete at least five minutes before the scheduled deletion time.

It may take up to five minutes for the cancellation of the namespace delete to apply.

Restore-EdgeKVNamespace -Network 'STAGING' -NamespaceID 'marketing'

The operation's response doesn't return any output.

Manage EdgeKV items

You need to populate the EdgeKV database with data that can be consumed by your EdgeWorkers function.

Add items

Add a group and items to your namespace on a given network with the New-EdgeKVItem command. You can also use this command to update the existing items. Groups classify the types of information saved in the database, and items represent those types using key-value pairs.

The target namespace ID must already exist before writing. Whereas the group ID is automatically created for you if it doesn't exist yet.

Note: The -GroupID here is the name of the group your items belong to, not your contract's group name.

$MyItemValue = @{
  currency = '$'
  flag = '/us.png'
  name = 'United States'
}

New-EdgeKVItem -Network 'STAGING' -NamespaceID 'marketing' -GroupID 'countries' -ItemID 'US' -Value $MyItemValue

New-EdgeKVItem -Network 'STAGING' -NamespaceID 'marketing' -GroupID 'countries' -ItemID 'US' -Value '"currency": "$", "flag": "/us.png", "name": "United States"'

Item was upserted in database, namespace marketing, group countries, and key US.

Read items

To read values of the items you added to the EdgeKV namespace and group on a given network, run the Get-EdgeKVItem operation.

Items recently written to EdgeKV can take 10 seconds or longer to read, and you may get a 404 error during that period.

# Get all
Get-EdgeKVItem -Network 'STAGING' -NamespaceID 'marketing' -GroupID 'countries'

# Get one
Get-EdgeKVItem -Network 'STAGING' -NamespaceID 'marketing' -GroupID 'countries' -ItemID 'US'

DE
US

{
  "currency": "$"
  "flag": "/us.png"
  "name": "United States"
}

Remove items

To remove a value of the item you previously added to the EdgeKV namespace and group on a given network, run the Remove-EdgeKVItem operation.

It can take 10 seconds or longer for a deleted item to be removed from the database.

Remove-EdgeKVItem -Network 'STAGING' -NamespaceID 'marketing' -GroupID 'countries' -ItemID 'DE'

Item was marked for deletion from database, namespace marketing, group countries, and key US.

If you try to run the Get-EdgeKVItem operation before the value has been updated globally, the stale data may be returned until the update is complete.

4. Generate an EdgeKV access token

You need an EdgeKV-specific access token to authorize an EdgeWorker ID to access data within a given namespace. This ensures that only authorized IDs gain access to the data with the proper controls.

Each token name needs to be unique and has a defined expiration of no longer than six months. You can't renew a token once it expires.

You can create a token with the New-EdgeKVAccessToken operation using one of these methods:

  • Specify the token's settings using individual parameters, including the token's name, the namespace you want to grant permissions to, and the permissions you want to assign.

    • Optionally, add the -AllowOnStaging and/or -AllowOnProduction switch parameters to define whether the token should have access to the Akamai staging and/or production network. Your namespace needs to exist on the staging and/or production network to use these switch parameters.
    • With the -RestrictToEdgeWorkerIds parameter, you can also define which EdgeWorker IDs are authorized to access EdgeKV via the token. If not specified, the token authorizes access for all IDs.
    New-EdgeKVAccessToken -Name 'my-token' -Namespace 'marketing' -Permissions 'rwd' -AllowOnStaging -RestrictToEdgeWorkerIds '12345, 54321'

    name                     : my-token
uuid                     : 123abcd4-5e6f-gh78-i90j-klm12no34p5q
expiry                   : 9999-12-31
tokenActivationStatus    : IN_PROGRESS
issueDate                : 2026-02-09
latestRefreshDate        : 
nextScheduledRefreshDate : 2026-04-09
cpcode                   : 12345
restrictToEdgeWorkerIds  : {54321}
allowOnStaging           : True
allowOnProduction        : False
namespacePermissions     : @{marketing=System.Object[]}

  • Provide the token's settings in a variable as a hashtable, PSCustomObject, or JSON string, and then pipe the variable to the New-EdgeKVAccessToken command or pass the variable in the -Body parameter.

    Parameter Required Description
    allowOnProduction ✔ When true, it gives a specific token access to the Akamai production network.
    allowOnStaging ✔ When true, it gives a specific token access to the Akamai staging network.
    name ✔ Your token's name. Use it when retrieving tokens by name with the Get-EdgeKVAccessToken operation.
    namespacePermissions ✔ An object where each key is a namespace name you want to grant permissions to and the value is an array of permissions: r for read, w for write, or d for delete. To list namespaces, run the Get-EdgeKVNamespace operation.

    All specified namespaces need the same database data access policy. A namespace's data access policy comes from the value of the -RestrictDataAccess parameter set when creating a namespace with the New-EdgeKVNamespace operation.
    restrictToEdgeWorkerIds A list of EdgeWorker IDs authorized to access EdgeKV via the token. If not specified, the token authorizes access for all IDs by default. 

    $MyTokenSettings = @{
  allowOnProduction = $false
  allowOnStaging = $true
  namespacePermissions = @{
    marketing = @("r", "w", "d")
  }
  name = "my-token"
  restrictToEdgeWorkerIds = @(12345, 54321)
}

$MyTokenSettings | New-EdgeKVAccessToken

    $MyTokenSettings = '{
  "allowOnProduction": false,
  "allowOnStaging": true,
  "namespacePermissions": {
    "marketing": ["r", "w", "d"]
  },
  "name": "my-token",
  "restrictToEdgeWorkerIds": ["12345", "54321"]
}'

$MyTokenSettings | New-EdgeKVAccessToken

Use the Get-EdgeKVAccessToken operation to view all available tokens or download a specific token you've created by providing its name.

# Get all
Get-EdgeKVAccessToken

# Get one
Get-EdgeKVAccessToken -TokenName 'my-token'

name                     : my-token
uuid                     : 123abcd4-5e6f-gh78-i90j-klm12no34p5q
expiry                   : 9999-12-31
tokenActivationStatus    : COMPLETE
issueDate                : 2026-02-09
latestRefreshDate        : 
nextScheduledRefreshDate : 2026-04-09

name                     : my-other-token
uuid                     : 9zy87xwv6-ut54-3sr2-1qp0-onm98lkj7i6
expiry                   : 9999-12-31
tokenActivationStatus    : IN_PROGRESS
issueDate                : 2026-02-09
latestRefreshDate        : 
nextScheduledRefreshDate : 2026-04-09

name                     : my-token
uuid                     : 123abcd4-5e6f-gh78-i90j-klm12no34p5q
expiry                   : 9999-12-31
tokenActivationStatus    : COMPLETE
issueDate                : 2026-02-09
latestRefreshDate        : 
nextScheduledRefreshDate : 2026-04-09
cpcode                   : 12345
restrictToEdgeWorkerIds  : {54321}
allowOnStaging           : True
allowOnProduction        : False
namespacePermissions     : @{marketing=System.Object[]}

If you need to refresh a previously created token before the scheduled automatic refresh, run the Update-EdgeKVAccessToken operation.

Update-EdgeKVAccessToken -TokenName 'my-token'

name                     : my-token
uuid                     : 123abcd4-5e6f-gh78-i90j-klm12no34p5q
expiry                   : 9999-12-31
tokenActivationStatus    : IN_PROGRESS
issueDate                : 2026-02-09
latestRefreshDate        : 2026-02-12
nextScheduledRefreshDate : 2026-04-12
cpcode                   : 12345
restrictToEdgeWorkerIds  : {12345,54321}
allowOnStaging           : True
allowOnProduction        : False
namespacePermissions     : @{marketing=System.Object[]}

You can revoke your token with the Remove-EdgeKVAccessToken operation if it's compromised or no longer needed. Before revoking a token, ensure that it's not in use in any EdgeWorker IDs. Requests to EdgeKV from an EdgeWorkers function using a revoked token return a 401 error.

Remove-EdgeKVAccessToken -TokenName my-token

name     uuid
----     ----
my-token 123abcd4-5e6f-gh78-i90j-klm12no34p5q

You can't retrieve the revoked token, and it's not listed anymore in the response of the Get-EdgeKVAccessToken operation.

5. Create a code bundle

To access the EdgeKV database, your EdgeWorkers code bundle must include the JavaScript helper library.

  1. Create a directory on your device for the code bundle files. Your bundle must contain the main.js and bundle.json files. See code bundle format for details.

  2. In the main.js file, include the EdgeWorkers library for your event handler functions for when to execute the code.

    Note: You can use the hello-world project from the EdgeWorkers GitHub repository or use one of the samples provided in the Akamai Edge Computing demo.

  3. In a manifest file named bundle.json, provide meta information, including at least your EdgeWorker's version number.

    Each time you create a new version of the code bundle, you need to increment the edgeworker-version in the bundle.json file.

    NameTypeDescriptionRequired
    edgeworker-versionStringYour EdgeWorker's version.✔️
    bundle-versionIntegerA bundle format version.
    api-versionStringA version of the JavaScript API when the EdgeWorkers code was created.
    descriptionStringA phrase describing the EdgeWorkers script function.
    miscObjectInformation you can include in the manifest to identify the EdgeWorkers function.

     {
   "edgeworker-version": "1.0",
   "bundle-version": 1,
   "api-version": "0.3",
   "description": "Perform redirect",
   "misc": {
     "author": "jsmith",
     "git-commit": "ab1cde2fghi34jk5lmn67opqr89stuv0wxyz",
     "updated": "2025-09-23"
   }
 }

  4. If you've linked an EdgeKV database, import the edgekv.js library file into your JavaScript bundle and configure it for your business needs. See the available EgdeKV helper library methods for details.

  5. The edgekv.js library automatically uses the appropriate token to access the corresponding namespace. If a token is missing, the EdgeKV methods throw an exception with a 401 error. In that case, add the edgekv_tokens.js file containing the EdgeKV access token to your EdgeWorkers code bundle directory.

    var edgekv_access_tokens = {
  "marketing": {
    "name": "my-token",
    "value": "123abcd4-5e6f-gh78-i90j-klm12no34p5q"
  }
}
export { edgekv_access_tokens };

  6. Compress your JavaScript code and manifest in a .tgz file, and add the bundle to your EdgeWorker version. You can do this in one of these ways:

    • Run the the New-EdgeWorkerVersion operation with the -CodeDirectory parameter to point to a local directory with your EdgeWorker code. This automatically bundles the code and creates a new EdgeWorker version. This also requires that your operating system contains the tar command.

      # Run by EdgeWorker name
New-EdgeWorkerVersion -EdgeWorkerName 'my-edgeworker' -CodeDirectory './my_bundle_directory'

# Run by EdgeWorker ID
 New-EdgeWorkerVersion -EdgeWorkerID 54321 -CodeDirectory './my_bundle_directory'

      edgeWorkerId   : 54321
version        : 1.0
accountId      : A-CCT1234
checksum       : ab01c23d456efghij7k89lmn0opqr123stuv456wxyzabcd7890efg1hij
sequenceNumber : 1
createdBy      : jsmith
createdTime    : 2/10/2026 3:48:53 PM

    • Alternatively, first run the tar command to bundle your code files.

      tar -czvf <your_bundle_filename>.tgz main.js bundle.json edgekv.js edgekv_tokens.js

      Then, run the New-EdgeWorkerVersion command with the -CodeBundle parameter to point to the location of your local .tgz file containing your EdgeWorker code.

      # Run by EdgeWorker name
New-EdgeWorkerVersion -EdgeWorkerName 'my-edgeworker' -CodeBundle './my_bundle_file.tgz'

# Run by EdgeWorker ID
New-EdgeWorkerVersion -EdgeWorkerID 54321 -CodeBundle './my_bundle_file.tgz'

6. Configure property rules

Before you can activate your EdgeWorker and use it on a network, it needs to be included in your property configuration.

  1. Get your property's rule tree as JSON snippets. The output is a directory at your current location containing your rule's configurations.

    Get-PropertyRules -PropertyName 'my-property' -PropertyVersion 'latest' -OutputSnippets -OutputDirectory './my-property-rules'

  2. Add the edgeWorker behavior to configure the EdgeWorker functionality to your rule's web traffic.

    • Set the enabled attribute to true to enable this feature.

    • Provide your EdgeWorker ID from step 1.

    • Enable or disable mPulse reports with data about EdgeWorkers errors generated due to JavaScript errors.

      Note: Before you enable mPulse reports for EdgeWorkers, you need to enable the mPulse behavior on your property.

    • Allow or disallow requests to continue processing following an EdgeWorkers event handler failure.

    "behaviors": [
  {
    "name": "edgeWorker",
    "options": {
      "enabled": true,
      "edgeWorkerId": "54321",
      "mPulse": false,
      "continueOnError": "false"
    }
  }
]

  3. Sets its criteria to scope where and when to execute the EdgeWorkers function. For example, you can set up the hostname criterion to match requests to a specific hostname.

     {
   "criteria": [
     {
       "name": "hostname",
       "options": {
         "matchOperator": "IS_ONE_OF",
         "values": [
           "my-site.com"
         ]
       }
     }
   ]
 }

  4. Configure your site's failover strategy with the failAction behavior to define what action to take in the event that an EdgeWorkers function fails.

    Also, add the edgeWorkersFailure criterion to verify the EdgeWorkers execution status and detect whether your JavaScript failed on edge servers.

    To ensure the failAction behavior works correctly, you should use it within a match, like matchResponseCode or originTimeout.

    "behaviors": [
   {
     "name": "failAction",
     "options": {
       "enabled": true,
       "actionType": "REDIRECT",
       "modifyProtocol": false,
       "redirectCustomPath": false,
       "redirectHostname": "alternate.site.com",
       "redirectHostnameType": "ALTERNATE",
       "redirectMethod": 302
     }
   }
 ],
 "criteria": [
   {
     "name": "edgeWorkersFailure",
     "options": {
       "execStatus": "FAILURE"
     }
   },
   {
     "name": "matchResponseCode",
     "options": {
       "matchOperator": "IS_ONE_OF",
       "values": [
         "500",
         "503",
         "504"
       ]
     }
   }
 ]

  5. Add your updated rules to your property, pointing to the appropriate directory.

    Send your entire rule tree back. Rules not returned are removed from your property.
    Set-PropertyRules -PropertyName 'my-property' -PropertyVersion 'latest' -InputDirectory './my-property-rules' -VersionNotes 'Adding an EdgeWorker'

  6. Activate the property containing your newly added EdgeWorker ID by providing a value for the network, STAGING or PRODUCTION, in the New-PropertyActivation command or its alias Deploy-Property.

    Deploy-Property -PropertyName 'my-property' -PropertyVersion 'latest' -Network 'STAGING' -NotifyEmails 'jsmith@email.com'

    activationLink                                                                                      activationId
--------------                                                                                      ------------
/papi/v1/properties/prp_12345/activations/atv_67890?contractId=ctr_C-0N7RAC7&groupId=grp_12345      atv_67890

If you haven't already, bundle your JavaScript and add it to your EdgeWorker. If you have, activate your EdgeWorker.

7. Deploy an EdgeWorker

When you're ready to apply your changes, activate your EdgeWorker version on either the STAGING or PRODUCTION network with the New-EdgeWorkerActivation operation or its alias Deploy-EdgeWorker.

It can take up to five minutes for an activation to complete.

# Activate by EdgeWorker name
Deploy-EdgeWorker -EdgeWorkerName 'my-edgeworker' -Version 'latest' -Network 'STAGING'

# Activate by EdgeWorker ID
Deploy-EdgeWorker -EdgeWorkerID 54321 -Version 'latest' -Network 'STAGING'

edgeWorkerId     : 54321
version          : 1.0
activationId     : 1
accountId        : A-CCT1234
status           : PRESUBMIT
network          : STAGING
createdBy        : jsmith
createdTime      : 2/11/2026 10:17:33 AM
lastModifiedTime : 2/11/2026 10:17:33 AM

Your activation will cycle through presubmit and pending states before it's complete and live on the network you chose.

Updated about 3 hours ago