In the EdgeKV data model, namespaces are logical containers of data. Namespaces also let administrators define user access and permissions to those namespaces using Akamai Control Center group membership. EdgeKV achieves this by tying a namespace to a Control Center access group.

You can learn about the access control model that applies to EdgeKV and all Akamai products in the Identity and Access Management documentation. Talk to your local Akamai administrator for more information about how to manage roles and access privileges of individual network users in Akamai Control Center.

About the EdgeKV granular namespace permission model

Akamai’s access control model lets an administrator define how users (often developers) in an organization interact with EdgeKV. A Control Center access group owns a namespace, while a role grants the permissions to that namespace. A user’s role in a group determines the permissions they have to act on the namespace (owned by the group). EdgeKV grants access on a per-namespace basis when each namespace is created. If you have READ_DATA for the namespace, you will be able to read any of the key-value pairs in the namespace, regardless of any logical groupings you create for the key-value pairs.

Permissions for a namespace can be very liberal, where it is made available to ANY access group under a contract with EdgeKV entitlement if the namespace is created using groupId=0. Alternatively, you could lock access to a namespace to a single access group when a groupId, such as groupId=1234, is specified. Note that an access group can only grant permissions to a namespace if the EdgeKV product is included on the contract associated with the group.

What a user can do with the resources they have access to is dictated by the permissions they hold. These permissions are granted in EdgeKV-specific roles, which are then assigned to users. For example, you may have access to the “marketing” namespace if you belong to access group 123, but unless you have the "EdgeKV Namespace - View-" permission you will be unable to get any details about the namespace itself. Similarly, if you do not have the "EdgeKV Data - Read-" permission, then you cannot read data contained in that namespace.

Namespace permissions also control which users can create EdgeKV tokens. To create a token, you need the token permissions as well as access to all the namespace resources associated with the token. To learn more about tokens you can refer to the section that describes how to set up EdgeKV access roles access tokens. For example, to create a token that grants read access to the “marketing” namespace and read/write access to the “engineering” namespace, you will need:

• The "EdgeKV Access Token - Create" permission for the access group that owns the "marketing" namespace.
• The "EdgeKV Access Token - Create" permission for the access group that owns the "engineering" namespace.
  If these two requirements are not satisfied, you will not be able to create a token. The same permission requirements apply to download a token.

 
The diagram below is a visual representation of the EdgeKV granular namespace permission model:

Set up EdgeKV access roles

Once EdgeKV is provisioned on contract, the administrator can add individual users to existing roles that include a defined set of user permissions. You can find detailed instructions for managing user roles in the Identity and Access Management documentation.

The administrator can also create custom roles by assigning one or more EdgeKV permissions to a role. This role can then be assigned to individual users. Refer to the Identity and Access Management documentation for instructions on how to create and assign a role. The administrator can also group users into these custom roles and grant permissions to a single namespace or multiple namespaces.

Use Identity and Access Management to manage EdgeKV roles

1. Refer to the Get Started with APIs instructions for information on how to create credentials in Akamai Control Center.

   To use EdgeKV management APIs or the Edge KV CLI, API credentials need to be created using the Admin role.

2. To add permissions to your API credentials, go to the Account Admin > Identity & access section in Akamai Control Center.

3. On the Users and API Clients tab, use the search bar to find your Client Name and open the client details.

4. Click the Edit API client button and scroll down to the APIs section.

5. Click the Select APIs radio button and type “edgekv” in the search bar.

6. Select the EdgeKV API.

7. Select READ-WRITE from the Access Level dropdown and submit your changes.

   Review the table below for information about predefined EdgeKV roles. The roles in the table correspond to abilities that a user holding that role can accomplish. The permission names are designed to be self-describing. For example, the “viewEdgeKvNamespace'' permission only allows a user the ability to view the details of an EdgeKV namespace, but not to write data to it.

👍

You can also use a custom role based on the existing EdgeKV Viewer, Publisher, Editor, or Admin roles shown above. When using the custom role, you need to add the CP Code - View CP Code Information- View CP Codes permission. Without the View CP Code permission, you may get a “500 Server Error, An internal error occurred” response.

📘

Staging permissions can only be used when the EdgeKV endpoint has the network set to STAGING. For example if you invoke GET “/edgekv/v1/networks/staging/namespaces/marketing” you'll get a 410 error if you don't belong to a group that has the “viewEdgeKvNamespaceStaging” permission.

If you invoke GET “/edgekv/v1/networks/production/namespaces/marketing” you'll get a 401 error if you don't belong to a group that has the “viewEdgeKvNamespaceStaging” permission.

8. Once you assign users to the EdgeKV roles you need to decide which access group should be used when creating a namespace. Each account in Akamai Control Center includes at least one access group.

You can also create a new access group to meet your requirements.

Apply granular namespace permissions

You should use the same Akamai Control Center access group ID for both an EdgeKV namespace and the EdgeWorker using that namespace. This helps prevent unauthorized users from downloading the EdgeKV token indirectly when working with an EdgeWorkers code bundle.

The steps below detail how to use an existing access group ID to create a namespace and an EdgeWorker ID. Access to Control Center Groups is controlled via the Identity and Access Management Application. For more information about roles and permissions that can be selected in IAM, please refer to the Identity and Access Management documentation.

1. Using the EdgeWorkers CLI, run this command to list the existing access groups associated with your account:

   akamai edgeworkers list-groups

   You can also use the short alias:
   akamai ew lg

2. Copy the groupId that you want to use from the first column.

📘

You can also use the Property Manager CLI to list the access groups associated with your account: akamai property-manager list-groups. Copy the number value after grp_ from the Group ID column.

3. Create a namespace using the selected access group ID from step one above.

4. Create an EdgeWorker ID again using the same access group ID.

Create a new namespace

1. To create a new namespace use:

POST /edgekv/v1/networks/{network}/namespaces
Content-Type: application/json
Request body: {
    "groupId": <access_groupId>,   
    "namespace": <namespaceId>, 
    "retentionInSeconds": <seconds>
}

2. Specify the {network} environment to execute the API request on. When you assign an access group to a namespace, the assignment is network-environment specific. You can specify staging or production networks, or both. You can choose to create an access group that allows full access to a namespace in staging, while creating another access group that restricts access to production namespaces. This is often useful when setting up deployment automation workflows.

   Permissions that end with Staging can only be used when the EdgeKV endpoint has the network URI set to STAGING. For example, if you invoke GET /edgekv/v1/networks/staging/namespaces/marketing you'll get a 410 error if you don't belong to an access group that has the “viewEdgeKvNamespaceStaging'' permission.

   If you invoke GET /edgekv/v1/networks/production/namespaces/marketing you will get a 401 error if you do not belong to an access group that has the “viewEdgeKvNamespaceStaging” permission.

3. For <access_groupId> specify the access control groupId that will have permission to this namespace. By default, the access group identifier is set to 0, which will allow all access groups in your account to access the namespace. If you want to restrict the namespace to a specific access group, enter the access group id. This value must be the same for both the staging and production instances of a namespace.

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

4. For <namespaceId> specify the name for the namespace.

5. For <retentionInSeconds> specify the retention period for data in this namespace in seconds, or 0 for indefinite retention.

Example namespace creation
Here is a sample request to create a namespace on the staging network with a defined group ID:

$ http --print=hbHB --auth-type edgegrid -a default: POST :/edgekv/v1/networks/staging/groupid = 12345/namespaces name=marketing retentionInSeconds=0
 
POST /edgekv/v1/networks/staging/namespaces HTTP/1.1
 
Content-Type: application/json
{
"groupId": 123456,       
"name": "marketing"
      "retentionInSeconds": 0
 
}

Here is a sample response:

HTTP/1.1 200 OK
Content-Type: application/json
{
"groupId": 123456,   
"geoLocation": "US",
"namespace: "marketing"
"retentionInSeconds": 0

Delete a namespace

When you schedule a namespace delete it immediately disables data read and write operations within the namespace. The namespace delete occurs three days from time when you scheduled the delete. You might want to delete a namespace if you're about to reach the limit on the number of namespaces per account.

🚧

A namespace delete deletes both the namespace and the content in the namespace.

1. To delete a namespace use:

$ http --print=hbHB --auth-type edgegrid -a default: DELETE :/edgekv/v1/networks/staging/groupid = 12345/namespaces name=marketing retentionInSeconds=0
 
DELETE /edgekv/v1/networks/production/namespaces HTTP/1.1
 
Content-Type: application/json
{
"namespace: "marketing",      
"network": "production"
}

Here is a sample response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "scheduledDeleteTime": "2024-07-18T14:48:33Z"
}

Once you schedule a delete you can check the date using the Get namespace delete time operation.

📘

You can cancel a namespace delete . You need to perform this operation at least 5 minutes before the scheduled delete time. You can also Reschedule a namespace delete.