Agent Sandbox:Manage API keys

Step 1: Create an API key

1. Log on to the Agent Sandbox console, select the destination region, and then choose Flash Edition > API Keys in the left-side navigation pane.

2. Select the destination resource group and team, and then click Create an API Key.

3. Configure the following parameters and complete the creation.

   Parameter	Description
   Description	The purpose of the API key, such as the application name and environment. This parameter maps to the apiKeyName API parameter and cannot exceed 128 characters in length. Use separate API keys for different applications or environments.
   Team	Select the team to which the API key is bound. You cannot rebind the key after the key is created.
   Expiration Time	Select Never or a custom point in time. For production environments, set an expiration time and complete the rotation before the key expires.
   IP Access Control	Optional. Configure a whitelist or a blacklist based on the outbound IPv4 address of the caller. For the rules, see Step 2: Configure IP access control.

After the API key is created, save the complete API key so that your application can use it to configure E2B_API_KEY.

To create an API key by calling an API operation, see CreateApiKey for the request parameters.

Step 2: Configure IP access control

The E2B-compatible API operations include sandbox, template, and volume operations. IP access control checks the source IPv4 address used to call these operations with the API key.

IP rules do not apply to native OpenAPI requests authenticated by Alibaba Cloud access credentials. IP rules also do not control access to the service ports of sandboxes or the outbound traffic of applications that run in sandboxes. For more information about outbound access control, see Network Access Control.

Before you configure the rules, verify the outbound IPv4 address that your application actually uses. If you access the operations over a Network Address Translation (NAT) gateway or a proxy, enter the corresponding outbound address. If you add 0.0.0.0/0 to the whitelist, all IPv4 addresses are allowed. If you add it to the blacklist, all IPv4 addresses are denied.

The following example updates the IP rules of an existing API key by using the UpdateApiKey operation of the native OpenAPI. Before you run the code, verify the ID of the destination API key to prevent changes to the access scope of other applications. The following environment variables are used:

In a terminal in which Alibaba Cloud access credentials are configured, set the parameters for this operation:

export SANDBOX_REGION_ID="cn-beijing"
export SANDBOX_ENDPOINT="sandbox.cn-beijing.aliyuncs.com"
export SANDBOX_API_KEY_ID="<YOUR-API-KEY-ID>"
export SANDBOX_ALLOWED_CIDR="<YOUR-OUTBOUND-IPV4>/32"

Save the following code as update_api_key_ip.py to configure a whitelist for the destination key. This operation overwrites the existing IP rules:

import os

from alibabacloud_sandbox20260820 import models
from alibabacloud_sandbox20260820.client import Client as SandboxClient
from alibabacloud_tea_openapi import utils_models as open_api_models


def require_env(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise RuntimeError(f"Missing environment variable: {name}")
    return value


client = SandboxClient(
    open_api_models.Config(
        access_key_id=require_env("ALIBABA_CLOUD_ACCESS_KEY_ID"),
        access_key_secret=require_env("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
        security_token=os.environ.get("ALIBABA_CLOUD_SECURITY_TOKEN"),
        region_id=require_env("SANDBOX_REGION_ID"),
        endpoint=require_env("SANDBOX_ENDPOINT"),
    )
)
api_key_id = require_env("SANDBOX_API_KEY_ID")

# Configure the whitelist.
response = client.update_api_key(
    api_key_id,
    models.UpdateApiKeyRequest(
        body=models.UpdateApiKeyInput(
            ip_whitelist=[
                models.IPConfig(
                    ip_address=require_env("SANDBOX_ALLOWED_CIDR"),
                    description="Fixed outbound IP of the application",
                )
            ],
            ip_blacklist=[],
        )
    ),
)
print(f"request_id={response.body.request_id}")

Run the example:

python update_api_key_ip.py

response = client.update_api_key(
    api_key_id,
    models.UpdateApiKeyRequest(
        body=models.UpdateApiKeyInput(
            ip_whitelist=[],
            ip_blacklist=[
                models.IPConfig(
                    ip_address="198.51.100.0/24",
                    description="Temporarily denied CIDR block",
                )
            ],
        )
    ),
)
print(f"request_id={response.body.request_id}")

response = client.update_api_key(
    api_key_id,
    models.UpdateApiKeyRequest(
        body=models.UpdateApiKeyInput(
            ip_whitelist=[],
            ip_blacklist=[],
        )
    ),
)
print(f"request_id={response.body.request_id}")

After the update, view the saved rules in the console or by calling DescribeApiKey, and verify that the expected calling environment can access the operations as configured. For all parameters, see UpdateApiKey.

Step 3: Use an API key in the SDK and CLI

The E2B SDK and the E2B CLI authenticate requests by using the plaintext API key. The endpoint corresponds to the region in which the API key resides. The following environment variables are used:

The following example uses the China (Beijing) region:

export E2B_API_KEY="<YOUR-API-KEY-VALUE>"
export E2B_API_URL="https://api.cn-beijing.sandbox.aliyuncs.com"
export E2B_DOMAIN="cn-beijing.sandbox.aliyuncs.com"

When you create a sandbox, make sure that the team to which the API key is bound matches the usage scope of the destination template. For more information about the parameters, see E2B SDK connection parameters.

View and edit API keys

The API Keys page shows the ID, masked value, description, status, and expiration time of an API key. When you modify the description, expiration time, or IP rules, verify the destination region and team.

To query API keys by calling API operations, use ListApiKeys and DescribeApiKey. To edit API keys by calling API operations, use UpdateApiKey.

Enable and disable an API key

After a key is disabled, the key can no longer be used for API authentication. When you re-enable the key, the key must also meet the expiration time and IP access control requirements. Call UpdateApiKey to set status to inactive to disable the key, or to active to enable the key. This operation can also be performed in the console.

If you find that a credential is leaked, disable or reset the key at the earliest opportunity, and update the credentials of the affected applications.

Reset an API key

ResetApiKey generates a new plaintext value for the same API key ID. After the reset, the old value becomes invalid and applications must use the new value. The team, expiration time, and IP rules remain unchanged.

After the reset, save the new value at once and update the configurations of your applications. If an application still uses the old value, the application fails authentication. If you need to continue using the old key during the switchover, perform the operations described in Zero-downtime rotation.

Zero-downtime rotation

1. In the same team, create a new API key and configure the required expiration time and IP access control settings.

2. Save the new key to the secret management system that your business uses, and update the configurations of your applications.

3. After you confirm that each application instance uses the new key and can call API operations as expected, disable the old key.

4. After you confirm that no business still depends on the old key, delete the old key.

This method retains the old key during the switchover. This method is suitable for rotation on expiration and planned credential replacement.

Delete an API key

You must disable the API key before you delete it. After you delete the key in the console or by calling DeleteApiKey, your business workloads should continue to use the new key that they have already switched to.

The authentication still fails after I configure an API key. What do I do?

Make sure that E2B_API_KEY is set to the complete plaintext value, and check whether the key is disabled, expired, reset, or deleted. Then verify the API URL, the domain name, and the region in which the key resides. Do not set E2B_API_KEY to an API key ID, a masked value, or an Alibaba Cloud AccessKey pair.

Requests are denied after I configure an IP whitelist. What do I do?

Check whether the actual outbound IPv4 address of the caller is in the whitelist. For requests forwarded over a NAT gateway, a proxy, or a continuous integration and continuous delivery (CI/CD) platform, the outbound address may differ from the local address. Verify the saved rules and the key that is in use, fix the rules, and then try again.

A request is denied by the API key policy. What do I do?

If the error message is request is not allowed by API key policy, the policy of the current API key does not allow the request. For storage mount requests, also check whether the API key policy allows the mount method and the storage type of the request. This type of denial occurs during API operation authorization. Changing the RAM role of the storage does not resolve the issue. For the mount requirements and policy limits of each storage type, see Append a volume mount.

The update of IP rules returns an invalid parameter error. What do I do?

Make sure that each address is a valid IPv4 address or IPv4 CIDR block, and that the whitelist and the blacklist are not both set to non-empty values. Verify that no remark exceeds the maximum length. To remove the restrictions, use two empty arrays instead of null. When you switch the list type, submit the complete destination rules.

Why am I unable to delete an API key?

Check whether the status of the key is inactive. Disable the key before you delete it. If the request is still denied, check whether the calling identity has the permission to delete API keys in the destination team.