API Key 管理

步骤一：创建 API Key

1. 登录智能体沙箱控制台，选择目标地域，在左侧导航栏选择极速版 > API Keys。

2. 选择目标资源组和 Team，单击创建 API Key。

3. 填写以下信息，确认后完成创建。

   配置项	说明
   描述	标识 API Key 的用途，例如应用名称和环境。对应 API 参数 apiKeyName，不超过 128 个字符。建议不同应用或环境分别使用 API Key。
   Team	选择该 API Key 绑定的 Team，创建后不能改绑。
   过期时间	可选择永不过期或自定义时间。生产环境建议设置过期时间，并在到期前完成轮换。
   IP 访问控制	可选。根据调用方的出口 IPv4 地址配置白名单或黑名单，规则见步骤二：配置 IP 访问控制。

创建成功后保存完整 API Key，供应用配置 E2B_API_KEY。

通过 API 创建时，请求参数参见CreateApiKey。

步骤二：配置 IP 访问控制

E2B 兼容接口包括 Sandbox、Template 和 Volume 等。IP 访问控制检查使用该 API Key 调用这些接口时的来源 IPv4 地址。

IP 规则不用于阿里云访问凭证认证的原生 OpenAPI 请求，也不控制沙箱业务端口访问和沙箱内应用的出站流量。出站访问控制，请参见网络访问控制。

配置前应确认应用实际使用的出口 IPv4 地址。通过 NAT 网关或代理访问时，应填写对应的出口地址。0.0.0.0/0 放入白名单表示允许所有 IPv4，放入黑名单表示拒绝所有 IPv4。

以下示例更新已有 API Key 的 IP 规则，使用原生 OpenAPI 的 UpdateApiKey。运行前确认目标 API Key ID，避免改变其他应用的访问范围。涉及以下环境变量：

在已配置阿里云访问凭证的终端中，设置本次操作参数：

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"

将以下代码保存为 update_api_key_ip.py，为目标 Key 配置白名单。该操作会覆盖已有 IP 规则：

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"缺少环境变量: {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")

# 配置白名单。
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="应用固定出口",
                )
            ],
            ip_blacklist=[],
        )
    ),
)
print(f"request_id={response.body.request_id}")

运行示例：

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="临时封禁网段",
                )
            ],
        )
    ),
)
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}")

更新后，通过控制台或DescribeApiKey查看保存的规则，并从预期的调用环境验证访问是否符合配置。完整参数，请参见UpdateApiKey。

步骤三：在 SDK 和 CLI 中使用 API Key

E2B SDK 和 E2B CLI 使用 API Key 明文值认证，接入地址与 API Key 所在地域对应。涉及以下环境变量：

以下以北京地域为例：

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"

创建沙箱时，确认 API Key 绑定的 Team 和目标模板的使用范围匹配。详细配置，请参见E2B SDK 接入参数说明。

查看与编辑

在 API Keys 页面查看 API Key 的 ID、掩码、描述、状态和过期时间。修改描述、过期时间或 IP 规则时，确认目标地域和 Team。

通过 API 查询和编辑分别使用ListApiKeys、DescribeApiKey和UpdateApiKey。

启用与禁用

禁用后，该 Key 无法继续用于接口认证；重新启用时，还需满足过期时间及 IP 访问控制要求。通过 UpdateApiKey 将 status 设置为 inactive （禁用）或 active（启用），也可以在控制台操作。

发现凭证泄露时，应及时禁用或重置该 Key，并更新受影响应用的凭证。

重置 API Key

ResetApiKey 为同一个 API Key ID 生成新的明文值。重置后旧值失效，应用需要使用新值；Team、过期时间和 IP 规则保持不变。

重置后立即保存新值并更新应用配置。应用仍使用旧值时，请求会认证失败。需要在切换过程中继续使用旧 Key 时，按平滑轮换操作。

平滑轮换

1. 在同一 Team 下创建新的 API Key，配置所需过期时间和 IP 访问控制。

2. 将新 Key 保存到业务使用的密钥管理系统，更新应用配置。

3. 确认各应用实例已使用新 Key 并能正常调用后，禁用旧 Key。

4. 确认没有业务继续依赖旧 Key 后，再将其删除。

这种方式在切换期间保留旧 Key，适合到期轮换和计划内凭证更换。

删除 API Key

删除前必须先禁用 API Key。通过控制台或DeleteApiKey删除后，业务应继续使用已切换的新 Key。

已配置 API Key，为什么仍然认证失败？

确认 E2B_API_KEY 使用完整明文值，检查 Key 是否被禁用、过期、重置或删除。再核对 API URL、Domain 和 Key 所在地域；不要将 API Key ID、掩码或阿里云 AccessKey 填入 E2B_API_KEY。

配置 IP 白名单后，请求被拒绝怎么办？

检查调用方实际出口 IPv4 地址是否在白名单中。经过 NAT 网关、代理或 CI/CD 平台的请求，出口地址可能与本机地址不同。核对保存后的规则以及当前使用的 Key，修正规则后重试。

请求被 API Key 权限策略拒绝怎么办？

错误消息为 request is not allowed by API key policy 时，表示当前 API Key 的权限策略不允许本次请求。存储挂载请求还需核对 API Key 策略是否允许本次的挂载方式和存储类型；这类拒绝发生在接口授权阶段，调整存储的 RAM 角色不能解决。各存储类型的挂载要求与策略限制，请参见追加挂载 Volume。

更新 IP 规则时提示参数不合法怎么办？

确认地址是有效的 IPv4 或 IPv4 CIDR 网段，黑白名单没有同时设置为非空，备注未超过长度限制。清空限制时使用两个空数组，不要传入 null；切换名单时应提交完整的目标规则。

为什么不能删除 API Key？

检查其状态是否为 inactive。先禁用，再执行删除；仍被拒绝时，核对调用身份是否具有目标 Team 内 API Key 的删除权限。