Skip to main content

Secret

Module for managing E2B secrets and workload identity helpers. Secret values are write-only: they are accepted by Secret.create and Secret.update but never returned by any read surface.

Constructors

Returns
Secret

Methods

create()

Create a new secret and its first value.
Parameters
Returns
Promise<SecretInfo> the secret’s ID, name, current version (1 for a new secret), metadata, and creation and update times.

destroy()

Destroy a secret, making all its versions inaccessible.
Parameters
Returns
Promise<boolean> true if the secret was destroyed, false if it was not found.

exists()

Check whether a secret exists.
Parameters
Returns
Promise<boolean> true if the secret exists, false otherwise.

fill()

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.
Parameters
Returns
string placeholder string resolving to the secret’s value.
Example

getInfo()

Get a secret’s metadata.
Parameters
Returns
Promise<SecretInfo> the secret’s ID, name, current version, metadata, and creation and update times.

iamToken()

Define a workload identity token to pass to iam.tokens when creating a sandbox.
Parameters
Returns
SandboxIamToken a token definition passable to iam.tokens.
Example

list()

List the project’s secrets.
Parameters
Returns
SecretPaginator paginator over the project’s secrets. Drain it page by page: while (paginator.hasNext) { const secrets = await paginator.nextItems() }.
Example

update()

Update a secret’s value by storing it as the secret’s new version.
Parameters
Returns
Promise<SecretInfo> the secret’s ID, name, new current version, metadata, and creation and update times.

SecretPaginator

Paginator for listing secrets.

Example

Constructors

Parameters
Returns
SecretPaginator

Accessors

hasNext

Get Signature
Returns true if there are more items to fetch.
Returns
boolean

nextToken

Get Signature
Returns the next token to use for pagination.
Returns
undefined | string

Methods

nextItems()

Get the next page of items.
Parameters
Returns
Promise<SecretInfo[]> List of items
Throws
Error if there are no more items to fetch. Call this method only if hasNext is true.

Interfaces

SecretCreateOpts

Properties

apiHeaders?

Additional headers to send with E2B API requests.

apiKey?

E2B API key to use for authentication.
Default

domain?

Domain to use for the API.
Default
E2B_DOMAIN // environment variable or e2b.app

headers?

Additional headers to send with the request.
Deprecated
Use apiHeaders instead.

httpVersion?

HTTP version for requests to the E2B API and to sandboxes (commands, filesystem, PTY). '2' multiplexes streams over shared connections; '1.1' pins them to HTTP/1.1 with one connection per concurrent request — for example when an intermediary on the path retires or mishandles long-lived HTTP/2 connections. Only applies in Node.
Default
E2B_HTTP_VERSION // environment variable or '2'

logger?

Logger to use for logging messages. It can accept any object that implements Logger interface—for example, console.

metadata?

Customer metadata to store with the secret.

proxy?

Proxy URL to use for requests. In case of a sandbox it applies to all requests made to the returned sandbox.
Example

requestTimeoutMs?

Timeout for requests to the API in milliseconds.
Default

retries?

Number of control-plane API retries after a 429, 502 or 503 response or a failure to establish the connection (refused, DNS, unreachable host). Any other network error (dropped connection, opaque browser/Workers TypeError) is retried too. A 502 and those network errors are not retried for operations that create a resource (e.g. sandbox creation) or append to one (secret update), as the server may already have processed them. A 429 is retried only with a valid, non-negative integer delta-seconds Retry-After header (HTTP-date and malformed values are not retried). 502 and 503 honor such a Retry-After when present; otherwise they and connection failures use exponential backoff with jitter starting at 100 ms (capped at 10 s). Retry waits use a 60-second total limit when request timeouts are disabled.
Default

signal?

An optional AbortSignal that can be used to cancel the in-flight request. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError.

validateApiKey?

Whether to validate the format of the E2B API key on the client side.
Deprecated
The API key format is no longer validated on the client side; this option has no effect.

SecretInfo

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

Properties

createdAt

Time when the secret was created.

metadata

Customer metadata of the secret.

name

Secret name, unique within the project.

secretId

Secret ID.

updatedAt

Time when the secret was last updated.

version

Version served to readers that do not name one.

SecretListOpts

Properties

apiHeaders?

Additional headers to send with E2B API requests.

apiKey?

E2B API key to use for authentication.
Default

domain?

Domain to use for the API.
Default
E2B_DOMAIN // environment variable or e2b.app

headers?

Additional headers to send with the request.
Deprecated
Use apiHeaders instead.

httpVersion?

HTTP version for requests to the E2B API and to sandboxes (commands, filesystem, PTY). '2' multiplexes streams over shared connections; '1.1' pins them to HTTP/1.1 with one connection per concurrent request — for example when an intermediary on the path retires or mishandles long-lived HTTP/2 connections. Only applies in Node.
Default
E2B_HTTP_VERSION // environment variable or '2'

limit?

Number of secrets to return per page.
Default

logger?

Logger to use for logging messages. It can accept any object that implements Logger interface—for example, console.

nextToken?

Token to the next page.

proxy?

Proxy URL to use for requests. In case of a sandbox it applies to all requests made to the returned sandbox.
Example

requestTimeoutMs?

Timeout for requests to the API in milliseconds.
Default

retries?

Number of control-plane API retries after a 429, 502 or 503 response or a failure to establish the connection (refused, DNS, unreachable host). Any other network error (dropped connection, opaque browser/Workers TypeError) is retried too. A 502 and those network errors are not retried for operations that create a resource (e.g. sandbox creation) or append to one (secret update), as the server may already have processed them. A 429 is retried only with a valid, non-negative integer delta-seconds Retry-After header (HTTP-date and malformed values are not retried). 502 and 503 honor such a Retry-After when present; otherwise they and connection failures use exponential backoff with jitter starting at 100 ms (capped at 10 s). Retry waits use a 60-second total limit when request timeouts are disabled.
Default

validateApiKey?

Whether to validate the format of the E2B API key on the client side.
Deprecated
The API key format is no longer validated on the client side; this option has no effect.

SecretUpdateOpts

Properties

apiHeaders?

Additional headers to send with E2B API requests.

apiKey?

E2B API key to use for authentication.
Default

domain?

Domain to use for the API.
Default
E2B_DOMAIN // environment variable or e2b.app

headers?

Additional headers to send with the request.
Deprecated
Use apiHeaders instead.

httpVersion?

HTTP version for requests to the E2B API and to sandboxes (commands, filesystem, PTY). '2' multiplexes streams over shared connections; '1.1' pins them to HTTP/1.1 with one connection per concurrent request — for example when an intermediary on the path retires or mishandles long-lived HTTP/2 connections. Only applies in Node.
Default
E2B_HTTP_VERSION // environment variable or '2'

logger?

Logger to use for logging messages. It can accept any object that implements Logger interface—for example, console.

metadata?

Customer metadata to store with the secret. When provided, replaces the stored metadata.

proxy?

Proxy URL to use for requests. In case of a sandbox it applies to all requests made to the returned sandbox.
Example

requestTimeoutMs?

Timeout for requests to the API in milliseconds.
Default

retries?

Number of control-plane API retries after a 429, 502 or 503 response or a failure to establish the connection (refused, DNS, unreachable host). Any other network error (dropped connection, opaque browser/Workers TypeError) is retried too. A 502 and those network errors are not retried for operations that create a resource (e.g. sandbox creation) or append to one (secret update), as the server may already have processed them. A 429 is retried only with a valid, non-negative integer delta-seconds Retry-After header (HTTP-date and malformed values are not retried). 502 and 503 honor such a Retry-After when present; otherwise they and connection failures use exponential backoff with jitter starting at 100 ms (capped at 10 s). Retry waits use a 60-second total limit when request timeouts are disabled.
Default

signal?

An optional AbortSignal that can be used to cancel the in-flight request. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError.

validateApiKey?

Whether to validate the format of the E2B API key on the client side.
Deprecated
The API key format is no longer validated on the client side; this option has no effect.

Type Aliases

SecretDestroyOpts


SecretExistsOpts


SecretGetInfoOpts