@storyblok/app-extension-auth

@storyblok/app-extension-auth is a JavaScript library for managing authentication in Storyblok apps.

Installation

npm install @storyblok/app-extension-auth@latest

Environment variables

APP_CLIENT_ID=your-app-client-id
APP_CLIENT_SECRET=your-app-client-secret
APP_URL=https://your-app.com/

• APP_CLIENT_ID: The public identifier for your app. Available in your Storyblok app settings.
• APP_CLIENT_SECRET: The secret shared between your app and Storyblok. Keep this private.
• APP_URL: Base URL for your app. Must be absolute and use HTTPS.

For example, using APP_URL=https://your-app.com/ creates these endpoints:

• https://your-app.com/storyblok for initiating authentication
• https://your-app.com/storyblok/callback for the OAuth2 callback

Configure authentication

Define the parameters once and reuse them across your app:

import { AuthHandlerParams } from '@storyblok/app-extension-auth'

export const params: AuthHandlerParams = {
 clientId: process.env.APP_CLIENT_ID,
 clientSecret: process.env.APP_CLIENT_SECRET,
 baseUrl: process.env.APP_URL,
 successCallback: '/',
 errorCallback: '/401',
 endpointPrefix: '/api/connect',
}

Optional parameters:

• successCallback: Redirect URL after successful login (default /).
• errorCallback: Redirect URL after failed login (default none, returns 401).
• endpointPrefix: Path prefix for authentication routes.

Example

baseUrl: "https://your-app.com/";
endpointPrefix: "api/authenticate";

This creates the following endpoints:

• https://your-app.com/api/authenticate/storyblok
• https://your-app.com/api/authenticate/storyblok/callback

Create routes

Use authHandler to process authentication requests.

Examples

Next.js

pages/api/connect/[...slugs].ts

import { authHandler } from "@storyblok/app-extension-auth";
import { params } from "@/config/auth";

export default authHandler(params);

Express

index.ts

import { authHandler } from "@storyblok/app-extension-auth";
import { params } from "@/config/auth";

app.all("/api/connect/*", authHandler(params));

Sign-in flow

Redirect users to /api/connect/storyblok to start authentication.

After login, users are redirected to the successCallback URL with these query parameters:

• userId
• spaceId

Session store

Use getSessionStore to manage sessions:

import { getSessionStore } from "@storyblok/app-extension-auth";

const sessionStore = getSessionStore(params)({ req, res });
//req: http.IncomingMessage;
//res: http.ServerResponse;

Available methods:

• get: Fetch a session by userId and spaceId.
• getAll: Fetch all sessions for a user.
• put: Store a session. Returns Promise<boolean>.
• remove: Delete a session. Returns Promise<boolean>

Note

sessionCookieStore still works, but getSessionStore is recommended.

Retrieve a session

import { getSessionStore, inferSessionQuery } from "@storyblok/app-extension-auth";
const sessionStore = getSessionStore(params)({ req, res });
const appSessionQuery = inferSessionQuery(req);
const appSession = await sessionStore.get(appSessionQuery);
if (!appSession) {
  // Not authenticated
  // redirect to /api/connect/storyblok
}

Use the session

The AppSession object contains user data and an access token for the Storyblok Management API:

const { userId, spaceId, region, roles, accessToken } = appSession;

Routing considerations

Storyblok apps run inside iframes.

Always pass spaceId and userId as query parameters when linking between pages, so the session can be retrieved:

const href = `/my/other/page?spaceId=${spaceId}&userId=${userId}`;

Local development

To test against a local Storyblok backend, add storyblokApiBaseUrl:

const params: AuthHandlerParams = {
 // ...
 storyblokApiBaseUrl: 'http://localhost:1234',
}

Expose your local server with a tool like ngrok:

ngrok http 3000

Further resources

Authentication OAuth2 flow

Space plugins