@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

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.

Example

Next.js

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

export default authHandler(params)

Express

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>.hint

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

Resources

• Authentication OAuth2 flow
• Space plugins