In 2024, Forge hosted storage will automatically include data residency. This means that all app data in Forge hosted storage will inherit data residency, in all current and future Atlassian-supported regions.

This implementation will provide your customers with greater control over their app data’s location. For more information, read this announcement.

Key-value store

The Storage API provides a simple key-value store you can use for storing unencrypted app data. Use this to store data that you'd like to retrieve through the storage.query tool.

To store sensitive data in a more secure manner, use the Secret store instead.

To start, import the Forge API package in your app, as follows:

1
2
import { storage } from '@forge/api';

Each installation of your app is subject to the Storage API's quotas and limits. See Storage quotas and Storage limits for more details.

The app storage API requires your app to have the storage:app scope. See Add scopes to call an Atlassian REST API guide to add new scopes to your app.

storage.set

Stores a JSON value with a specified key. Forge resolves write conflicts using a last-write-wins strategy.

You can learn more about limits and quotas here.

You don't need to include any identifiers for apps or installations in your key.

Internally, Forge automatically prepends an identifier to every key, mapping it to the right app and installation. This lets you use the full key length without risking conflicts across apps or installations.

Method signature

1
2
storage.set(key: string, value: array | boolean | number | object | string ): Promise<void>;

Example

Sets the key example-key to one of the supported value types.

1
2
// array
storage.set('example-key', [ 'Hello', 'World' ]);

// boolean
storage.set('example-key', true);

// number
storage.set('example-key', 123);

// object
storage.set('example-key', { hello: 'world' });

// string
storage.set('example-key', 'Hello world');

storage.get

Gets a value by key. If the key doesn't exist, the API returns undefined.

Method signature

1
2
storage.get(key: string): Promise<array | boolean | number | object | string>;

Example

Gets the value associated with the key example-key.

1
2
// Read the value for key `example-key`
await storage.get('example-key');

storage.delete

Deletes a value by key, this succeeds whether the key exists or not. Write conflicts are resolved using a last-write-wins strategy.

While you can use the storage.delete method to delete app storage when deleting an app, we recommend you raise a ticket with the Atlassian Marketplace team to handle this for you. See Retiring your app for more details.

Method signature

1
2
storage.delete(key: string): Promise<void>;

Example

Deletes the value associated with the key example-key, if it hasn't already been deleted.

1
2
// Delete the value with the key `key`
await storage.delete('example-key');

storage.query

Builds a query which returns a set of entities matching the provided list of criteria. See Query for more information on building and executing queries.

storage.query does not return secret values set by storage.setSecret.

Method signature

1
2
storage.query(): Query

Examples

1
2
import { storage, startsWith } from '@forge/api';

await storage.query()
  // Filter the response to only keys that start with the string 'value'
  .where('key', startsWith('value'))

  // Limit the result size to 10 values
  .limit(10)

  // Use the cursor provided (returned from a previous invocation)
  .cursor('...')

  // Get a list of results
  .getMany();