Tool-Instance Storage

toolInstanceStorage API (Server-Side)

The toolInstanceStorage API allows you to persist data per tool instance across all users, making it ideal for storing shared credentials or authentication tokens like OAuth access tokens.

This storage is available in the Server-Side Variable Runtime Environment and is scoped to the tool instance, meaning it is shared across users but isolated per tool.

---

Primary Use Case

• Storing authentication tokens or other shared values that need to persist across multiple users but within a single tool context.

Examples:

• OAuth access_token

• API keys or session credentials

• Rate-limiting counters per tool

---

Available Functions

1. this.toolInstanceStorage.write(name, value, expirationTimestamp)

Stores a value under a given key, scoped to the tool instance.

Parameters

Placeholder	Description	Type	Required	Example
<NAME>	The key used to store and access the value	string		"auth_token"
<VALUE>	The value to be stored (can be any data type)	any		"123abcd123.11111111"
<EXPIRATION TIMESTAMP>	The expiration time in milliseconds since epoch	number (ms since epoch)		1740555149453

Example

async function() {
  // Retrieve OAUTH token from external system
  const access_token = await fetchTokenFromAPI(); // custom function
  this.toolInstanceStorage.write(
    "auth_token",
    access_token,
    Date.now() + 86400000 // 24 hours
  );
  return access_token;
}

---

2. this.toolInstanceStorage.read(name)

Reads a stored value from the tool instance storage using a key.

Parameters

Placeholder	Description	Type	Required	Example
<NAME>	The key under which the value is stored	string		"auth_token"

Example

async function() {
  const access_token = this.toolInstanceStorage.read("auth_token");
  return access_token || "";
}

---

3. this.toolInstanceStorage.delete(name)

Deletes a stored value by key from the tool instance storage.

Parameters

Placeholder	Description	Type	Required	Example
<NAME>	The key under which the value is stored	string		"auth_token"

Example

jsCopyEditasync function() {
  this.toolInstanceStorage.delete("auth_token");
  return "";
}

---

✅ Best Practices

• Use this storage only for values shared across users, like authentication or session credentials.

• Set appropriate expiration timestamps to avoid stale or expired data.

• Avoid storing personal user data here — use userStorage for user-specific persistence.

---

Summary

The toolInstanceStorage API is a powerful mechanism in JENTIS Server-Side Variables to persist and share state across users for a given tool. Ideal for managing authentication flows, API keys, and other shared resources, it provides controlled, server-side storage with expiration and full read/write/delete support.

For further guidance, see the Authentication Token Integration Guide or reach out to JENTIS Support.