Skip to content

Introduction to Space Plugins

Space plugins are available across an entire space, making them ideal for embedding functionality that doesn’t require direct content editing. Examples include the Broken Links Checker, which scans for broken links, or an analytics app that displays data directly in Storyblok.

Space plugins require self-hosting, and only users with access to the Partner Portal or an organization can register them.

First, create a new space plugin: in the Partner Portal or your organization open Extensions → Space, and select Create new.

Name the plugin, enter a unique string in the ID/Slug field, and Save.

To communicate with Storyblok, open the plugin, select OAuth 2.0 and Pages, and check the following:

Setting Description
Client Identifier and Client Secret Use as environment variables in your application.
Index to your page and Redirection endpoint Define the URLs in the Production and Preview sections based on your app’s hosting domain.
  1. In the General tab, copy the Install Link.
  2. Open the URL in your browser, and select a space to install the plugin.

To display the plugin in the space, run the plugin locally and enter the local URLs in the OAuth 2.0 and Pages settings. The first time someone opens the plugin, Storyblok shows the OAuth consent screen. An admin has to approve the plugin before editors can use the plugin.

Server-side code reads the accessToken, region, and spaceId of the current space and user from the session that the @storyblok/app-extension-auth library stores.

Storyblok adds the space_id and user_id query parameters to the plugin URL, and inferSessionQuery() reads them from the request.

Pass the same parameters you pass to authHandler as authHandlerParams:

import { getSessionStore, inferSessionQuery } from "@storyblok/app-extension-auth";
const sessionStore = getSessionStore(authHandlerParams)({ req, res });
const appSessionQuery = inferSessionQuery(req);
const { accessToken, region, spaceId } = await sessionStore.get(appSessionQuery);

To call the Management API, send requests that reference the same values. The following example lists the stories in the space:

new StoryblokClient({
oauthToken: `Bearer ${accessToken}`,
region,
}).get(`spaces/${spaceId}/stories`, {
sort_by: "updated_at:desc",
});

To let each space store its individual plugin settings, open the Partner Portal or your organization, select Extensions, open the plugin, and select Details → Enable settings on space level. To read the plugin’s per-space settings, use an OAuth access token.

The following example uses the Management API host to retrieve settings for a space in the EU:

Terminal window
curl --location "https://mapi.storyblok.com/v1/spaces/{space_id}/app_provisions/{app_id}" \
--header "Authorization: Bearer {oauth_token}"

To match the overall interface, use Storyblok’s design system for Vue 3 (npm install @storyblok/design-system) or Storyblok MUI for React-based frameworks.

Was this page helpful?

What went wrong?

This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.