# 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`                  | <i class="fa-square-check">:square-check:</i> | `"auth_token"`          |
| `<VALUE>`                | The value to be stored (can be any data type)       | `any`                     | <i class="fa-square-check">:square-check:</i> | `"123abcd123.11111111"` |
| `<EXPIRATION TIMESTAMP>` | The expiration time in **milliseconds** since epoch | `number` (ms since epoch) | <i class="fa-square-check">:square-check:</i> | `1740555149453`         |

**Example**

```js
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` | <i class="fa-square-check">:square-check:</i> | `"auth_token"` |

**Example**

```js
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` | <i class="fa-square-check">:square-check:</i> | `"auth_token"` |

**Example**

```js
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.