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.
Register the space plugin
Section titled “Register the space plugin”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. |
Install the space plugin
Section titled “Install the space plugin”- In the General tab, copy the Install Link.
- 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.
Integrate with the Management API
Section titled “Integrate with the Management API”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",});Space-level configuration
Section titled “Space-level configuration”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:
curl --location "https://mapi.storyblok.com/v1/spaces/{space_id}/app_provisions/{app_id}" \ --header "Authorization: Bearer {oauth_token}"Style the space plugin
Section titled “Style the space plugin”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?
This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.
- Need help?Contact support (opens in a new window)
- Something isn’t right?Check system status (opens in a new window)
Get in touch with the Storyblok community