From 9614e5487fe554b1e49221a4fe18521f16a6eb11 Mon Sep 17 00:00:00 2001
From: Mish Ushakov <10400064+mishushakov@users.noreply.github.com>
Date: Fri, 24 Jul 2026 18:42:57 +0200
Subject: [PATCH] docs: add sandbox workload identity (IAM tokens) page

Documents the new `iam` option on Sandbox.create and the Secret
iamToken/iam_token helper from e2b-dev/E2B#1606.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs.json                          |  3 +-
 docs/sandbox/workload-identity.mdx | 64 ++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 docs/sandbox/workload-identity.mdx

diff --git a/docs.json b/docs.json
index 7922cd0a..e59f4a1a 100644
--- a/docs.json
+++ b/docs.json
@@ -145,7 +145,8 @@
               "docs/sandbox/connect",
               "docs/sandbox/pty",
               "docs/sandbox/ssh-access",
-              "docs/sandbox/secured-access"
+              "docs/sandbox/secured-access",
+              "docs/sandbox/workload-identity"
             ]
           },
           {
diff --git a/docs/sandbox/workload-identity.mdx b/docs/sandbox/workload-identity.mdx
new file mode 100644
index 00000000..df453193
--- /dev/null
+++ b/docs/sandbox/workload-identity.mdx
@@ -0,0 +1,64 @@
+---
+title: "Workload identity"
+sidebarTitle: Workload identity
+description: "Give sandbox workloads short-lived identity tokens instead of long-lived secrets."
+---
+
+Workload identity lets code running in a sandbox prove who it is with short-lived identity tokens instead of long-lived credentials.
+Rather than baking cloud API keys into a template or passing them as environment variables, you define named workload tokens when creating the sandbox.
+Each token is scoped to an audience — the external service that will verify it, such as AWS STS — and the service can exchange the token for its own temporary credentials.
+
+<Note>
+Workload identity is currently available for selected teams. If it's not enabled for your team, sandbox creation with the `iam` option fails with `Sandbox IAM workload tokens are not available for your team.` — [contact us](/docs/support) to get access.
+</Note>
+
+## Configure
+
+Pass the `iam` option when creating a sandbox. A non-empty `tokens` map enables workload identity for the sandbox.
+Each entry maps a token name you choose to a token definition, which you can create with the `Secret` helper.
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Sandbox, Secret } from 'e2b'
+
+const sandbox = await Sandbox.create({
+  iam: {
+    tokens: {
+      aws: Secret.iamToken({
+        audience: 'sts.amazonaws.com',
+        tokenType: 'JWT-SVID',
+      }),
+    },
+  },
+})
+```
+```python Python
+from e2b import Sandbox, Secret
+
+sandbox = Sandbox.create(
+    iam={
+        "tokens": {
+            "aws": Secret.iam_token(
+                audience="sts.amazonaws.com",
+                token_type="JWT-SVID",
+            ),
+        },
+    },
+)
+```
+</CodeGroup>
+
+You can also pass plain token definitions instead of using the `Secret` helper — `{ audience, tokenType }` objects in JavaScript, `{"audience": ..., "token_type": ...}` dicts in Python.
+
+## Token definitions
+
+Each token definition has two fields:
+
+| Field | Description |
+|-------|-------------|
+| `audience` | Required. The audience of the workload token — the identifier of the service that will verify it. Stored exactly as provided. |
+| `tokenType` (JavaScript) / `token_type` (Python) | Required. The workload token type. `"JWT-SVID"` is the only type supported today; more types may be added later. |
+
+Token names (the keys of the `tokens` map) are yours to choose and must not be empty. A sandbox can define up to **5** workload tokens.
+
+Creating a sandbox without the `iam` option, or with an empty `tokens` map, leaves workload identity disabled.