> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e2b.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret

## SecretPaginator

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
class SecretPaginator(SecretPaginatorBase)
```

Paginator for listing secrets.

**Example**:

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
paginator = Secret.list()

while paginator.has_next:
    secrets = paginator.next_items()
    print(secrets)
```

### next\_items

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
def next_items(**opts: Unpack[ApiParams]) -> List[SecretInfo]
```

Returns the next page of secrets.

Call this method only if `has_next` is `True`, otherwise it will raise an exception.

**Arguments**:

* `opts`: Per-call connection options (e.g. `api_key`, `domain`,
  `headers`, `request_timeout`). When provided, this call uses these
  options instead of the ones the paginator was constructed with.

**Returns**:

List of secret metadata.

## Secret

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
class Secret(SecretBase)
```

Module for managing E2B secrets and workload identity helpers.

Secret values are write-only: they are accepted by `create` and
`update` but never returned by any read surface.

### create

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
def create(cls,
           name: str,
           value: str,
           metadata: Optional[Dict[str, str]] = None,
           **opts: Unpack[ApiParams]) -> SecretInfo
```

Create a new secret and its first value.

**Arguments**:

* `name`: Name of the secret, unique within the project.
* `value`: Secret value. Write-only — never returned by the API.
* `metadata`: Customer metadata to store with the secret.

**Returns**:

The secret's ID, name, current version (`1` for a new
secret), metadata, and creation and update times.

### update

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
def update(cls,
           secret: str,
           value: str,
           metadata: Optional[Dict[str, str]] = None,
           **opts: Unpack[ApiParams]) -> SecretInfo
```

Update a secret's value by storing it as the secret's new version.

**Arguments**:

* `secret`: Secret ID or name.
* `value`: New secret value. Write-only — never returned by the API.
* `metadata`: Customer metadata to store with the secret. When
  provided, replaces the stored metadata.

**Returns**:

The secret's ID, name, new current version, metadata, and
creation and update times.

### get\_info

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
def get_info(cls, secret: str, **opts: Unpack[ApiParams]) -> SecretInfo
```

Get a secret's metadata.

**Arguments**:

* `secret`: Secret ID or name.

**Returns**:

The secret's ID, name, current version, metadata, and
creation and update times.

### list

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
def list(cls,
         limit: Optional[int] = None,
         next_token: Optional[str] = None,
         **opts: Unpack[ApiParams]) -> SecretPaginator
```

List the project's secrets.

**Arguments**:

* `limit`: Number of secrets to return per page.
* `next_token`: Token to the next page.

**Returns**:

Paginator over the project's secrets. Drain it page by page:

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
paginator = Secret.list(limit=50)
while paginator.has_next:
    secrets = paginator.next_items()
```

### exists

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
def exists(cls, secret: str, **opts: Unpack[ApiParams]) -> bool
```

Check whether a secret exists.

**Arguments**:

* `secret`: Secret ID or name.

**Returns**:

`True` if the secret exists, `False` otherwise.

### destroy

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
def destroy(cls, secret: str, **opts: Unpack[ApiParams]) -> bool
```

Destroy a secret, making all its versions inaccessible.

**Arguments**:

* `secret`: Secret ID or name.

**Returns**:

`True` if the secret was destroyed, `False` if it was not found.

## SecretBase

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
class SecretBase(ClientFactory)
```

Module for managing E2B secrets and workload identity helpers.

Secret values are write-only: they are accepted by `create` and
`update` but never returned by any read surface.

### fill

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@staticmethod
def fill(secret: str) -> str
```

Format a placeholder that the runtime resolves to the secret's

current value.

This is a local formatting helper and makes no network call — it does
not check whether the named secret exists. An unknown reference fails
server-side when the placeholder is resolved.

**Arguments**:

* `secret`: Secret name.

**Returns**:

Placeholder string resolving to the secret's value.
Example:

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
Secret.fill("openai-api-key")
```

### iam\_token

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@staticmethod
def iam_token(*, audience: str,
              token_type: SandboxIamTokenType) -> SandboxIamToken
```

Define a workload identity token to pass to `iam.tokens` when

creating a sandbox.

**Arguments**:

* `audience`: Audience of the workload token, stored exactly as provided.
* `token_type`: Workload token type.

**Returns**:

A token definition passable to `iam.tokens`.
Example:

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
sandbox = Sandbox.create(
    iam={
        "tokens": {
            "aws": Secret.iam_token(
                audience="sts.amazonaws.com",
                token_type="JWT-SVID",
            ),
        },
    },
)
```

## SecretInfo

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@dataclass
class SecretInfo()
```

Metadata of a secret. Secret values are write-only and never returned.

### secret\_id

Secret ID.

### name

Secret name, unique within the project.

### version

Version served to readers that do not name one.

### metadata

Customer metadata of the secret.

### created\_at

Time when the secret was created.

### updated\_at

Time when the secret was last updated.

## AsyncSecretPaginator

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
class AsyncSecretPaginator(SecretPaginatorBase)
```

Paginator for listing secrets.

**Example**:

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
paginator = AsyncSecret.list()

while paginator.has_next:
    secrets = await paginator.next_items()
    print(secrets)
```

### next\_items

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
async def next_items(**opts: Unpack[ApiParams]) -> List[SecretInfo]
```

Returns the next page of secrets.

Call this method only if `has_next` is `True`, otherwise it will raise an exception.

**Arguments**:

* `opts`: Per-call connection options (e.g. `api_key`, `domain`,
  `headers`, `request_timeout`). When provided, this call uses these
  options instead of the ones the paginator was constructed with.

**Returns**:

List of secret metadata.

## AsyncSecret

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
class AsyncSecret(SecretBase)
```

Module for managing E2B secrets and workload identity helpers.

Secret values are write-only: they are accepted by `create` and
`update` but never returned by any read surface.

### create

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
async def create(cls,
                 name: str,
                 value: str,
                 metadata: Optional[Dict[str, str]] = None,
                 **opts: Unpack[ApiParams]) -> SecretInfo
```

Create a new secret and its first value.

**Arguments**:

* `name`: Name of the secret, unique within the project.
* `value`: Secret value. Write-only — never returned by the API.
* `metadata`: Customer metadata to store with the secret.

**Returns**:

The secret's ID, name, current version (`1` for a new
secret), metadata, and creation and update times.

### update

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
async def update(cls,
                 secret: str,
                 value: str,
                 metadata: Optional[Dict[str, str]] = None,
                 **opts: Unpack[ApiParams]) -> SecretInfo
```

Update a secret's value by storing it as the secret's new version.

**Arguments**:

* `secret`: Secret ID or name.
* `value`: New secret value. Write-only — never returned by the API.
* `metadata`: Customer metadata to store with the secret. When
  provided, replaces the stored metadata.

**Returns**:

The secret's ID, name, new current version, metadata, and
creation and update times.

### get\_info

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
async def get_info(cls, secret: str, **opts: Unpack[ApiParams]) -> SecretInfo
```

Get a secret's metadata.

**Arguments**:

* `secret`: Secret ID or name.

**Returns**:

The secret's ID, name, current version, metadata, and
creation and update times.

### list

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
def list(cls,
         limit: Optional[int] = None,
         next_token: Optional[str] = None,
         **opts: Unpack[ApiParams]) -> AsyncSecretPaginator
```

List the project's secrets.

**Arguments**:

* `limit`: Number of secrets to return per page.
* `next_token`: Token to the next page.

**Returns**:

Paginator over the project's secrets. Drain it page by page:

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
paginator = AsyncSecret.list(limit=50)
while paginator.has_next:
    secrets = await paginator.next_items()
```

### exists

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
async def exists(cls, secret: str, **opts: Unpack[ApiParams]) -> bool
```

Check whether a secret exists.

**Arguments**:

* `secret`: Secret ID or name.

**Returns**:

`True` if the secret exists, `False` otherwise.

### destroy

```python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
@classmethod
async def destroy(cls, secret: str, **opts: Unpack[ApiParams]) -> bool
```

Destroy a secret, making all its versions inaccessible.

**Arguments**:

* `secret`: Secret ID or name.

**Returns**:

`True` if the secret was destroyed, `False` if it was not found.