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.

You can create one or more EdgeKV access tokens per namespace, or create tokens that grant access to multiple namespaces. Before creating your tokens refer to the to the Product limits section to make sure you stay within the overall limit for the number of allowed tokens per account.

To create a token you need to have the EdgeKV Access Token - Create - Create a new EdgeKV Access Token permission associated with your API client.

When you create an EdgeKV access token, you must assign it a unique name. Tokens are securely stored in Akamai’s internal systems. Anyone with the EdgeKV Access Token - View- List EdgeKV Access Token permission can list tokens or use the assigned name to retrieve a token.

The token create operation will fail if you attempt to create a token with an existing name.

Enhanced token workflow

As of August 30, 2024 any new tokens that you create will refresh automatically. These new tokens will no longer expire. When you use the Create an access token endpoint to create a new token, the expiry date is not required in the request. You can still, however, revoke the token at any time. You can also force a token refresh before the automatic refresh is scheduled to occur.

📘

All tokens created using automatic refresh have an expiry date of 9999-12-31. Tokens generated before the token enhancement will show the unique expiry date provided when it was created.

Helper library

You need version 0.6.2 or higher of the helper library in your EdgeWorkers code bundle to use the enhanced token workflow. Any tokens created before the enhancement was activated are not compatible with version 0.6.2 of the helper library. For instructions on how to update your code bundle go to, Create a code bundle.

The JWT value is not provided when you Download an access token. Tokens that are created using automatic refresh include details such as the next scheduled refresh date and the latest refresh date.

Any pre-existing tokens created before August 30, 2024 will not be automatically refreshed. You can still get information about these older tokens using the List access tokens operation. You can continue to use these tokens with a helper library 0.6.1 or lower until the token expires. Follow the steps in Create an access token to replace these tokens before they expire.

EdgeWorker ID

Access tokens used by an EdgeWorker ID are stored in your local edgekv_tokens.js file, which must be included in an EdgeWorkers code bundle. You can use the administrative API or CLI to create or retrieve a token. The CLI also provides the option to update the edgekv_tokens.js file automatically, whereas using the administrative API requires the use of a separate tool to update the file.

The edgekv_access_tokens dictionary in the edgekv_tokens.js file must be updated with new token name and token value fields if those values change. These fields are added under a parent key called namespace-.

For example, if we create a token named default_token with a UUID of 26dcc842-4458-44e6-8a4e-ec26ab65b46e for the default namespace and another called marketing_token with a UUID of 8b09dd55-c755-45ef-b7b1-2c83db1e5f7e for the marketing namespace, the contents of the file would look similar to this example:

var edgekv_access_tokens = {
                    "namespace-default": {
                       "name": "default_token",
                       "reference": "26dcc842-4458-44e6-8a4e-ec26ab65b46e"
                   },
                   "namespace-marketing": {
                     "name": "marketing_token",
                     "reference": "8b09dd55-c755-45ef-b7b1-2c83db1e5f7e"
                  }
}
export { edgekv_access_tokens };

Troubleshoot access tokens

You need version 0.6.2 or higher of the JavaScript helper library to enable automatic token refresh. In version 0.6.2 and forward the helper library associates a UUID to the reference attribute name. The value attribute that was previously used to store the older JWT itself cannot be used for tokens created using automatic token refresh.

Old edgekv.js file version in the bundle

If you include a version earlier than 0.6.2 of the edgekv.js file in the EdgeWorkers code bundle you will receive a validation error. To resolve the error below, you need to get the latest version of the JavaScript helper library and include it in your code bundle.

The edgekv.js helper library version is invalid: EdgeKV version 0.6.1 is below the minimum accepted version 0.6.2

The new token UUID includes a legacy "value" attribute

When a legacy value attribute is used to assign a new token UUID instead of the reference attribute, the EdgeWorkers code bundle will fail validation and the following error message appears.

The following EdgeKV access tokens are invalid:
namespace-EKVEWInterop_unrestricted contains a JWT token with an invalid format

You can only use the reference attribute to associate token UUIDs.

An older JWT token with new "reference" attribute

The following EdgeWorkers code bundle error message will appear if an invalid token UUID is assigned to the reference attribute.

The following EdgeKV access tokens are invalid:
<your old JWT>

To resolve this issue, make sure that the associated token UUID is valid and the status is COMPLETE. To do this, look up the token name using the List access tokens operation.