# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.jentis.com/developer-guide/variables/server-side-variables/public-function-scope/tool-instance-level-storage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.