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.

Storage

Forge apps are able to store, retrieve, and delete data from storage in Atlassian's cloud using two different APIs.

App storage

The app storage API is a key-value storage API, which enables your app to store data for specific Jira or Confluence sites. The app storage API stores data partitioned by product and site, and is accessible only to your app.

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.

Custom entities (preview)

This section describes a Forge preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.

We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA). For more information, see Forge release phases: EAP, Preview, and GA.

Custom entities are user-defined data structures for storing app data. Forge's storage API lets you query data stored in these structures using a wide array of query conditions. These query conditions make it possible to build advanced, complex queries to suit your app's operations.

See Complex queries (preview) for more detailed information about setting custom entities and building queries for them.

Recommendations

When using the app storage API, we strongly recommend that you:

only use encrypted environment variables and storage.setSecret to store secrets or credentials in your app.
avoid using the app Storage API for storing files.
avoid employing data models with entities that grow in an unbounded manner (in terms of depth and/or size), as this may lead to exceeding storage limits.

The Atlassian Cloud backs up the entire hosted storage for disaster recovery. This includes content stored from the Forge storage API.

Properties

Properties are a set of APIs backed by entity properties in Jira and content properties in Confluence. These APIs allow your app to store and retrieve data for a specific Jira or Confluence site. This data is accessible to all apps installed within the site as well as users.

Modules used with the UI kit

Use UI kit hooks reference documentation for information on the functions that let you manage the data you need to render your app.

If you’re storing data relating to a particular instance of a Forge macro, you should use Forge macro configuration. Macro configuration enables different instances of the macro that appear on the same page or blog to store their data separately.

Other modules

Use the Properties API in the runtime for modules that don't support UI.