---
title: @storyblok/app-extension-auth
description: @storyblok/app-extension-auth is a JavaScript library for managing authentication in Storyblok apps.
url: https://storyblok.com/docs/libraries/js/app-extension-auth-helper
---

# @storyblok/app-extension-auth

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

## Installation

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

## Environment variables

.env

```bash
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:

```ts
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

```js
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

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

export default authHandler(params);
```

#### Express

index.ts

```js
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:

```js
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

```js
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:

```js
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:

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

## Local development

To test against a local Storyblok backend, add `storyblokApiBaseUrl`:

```ts
const params: AuthHandlerParams = {
  // ...
  storyblokApiBaseUrl: "http://localhost:1234",
};
```

Expose your local server with a tool like `ngrok`:

```bash
ngrok http 3000
```

## Further resources

[Authentication OAuth2 flow](https://www.storyblok.com/docs/plugins/oauth-authorization-flow)

[Space plugins](/docs/plugins/space-plugins)

## Pagination

-   [Previous: Field Plugin SDK](/docs/libraries/js/field-plugin-sdk)
-   [Next: Content Delivery API Client](/docs/libraries/php/content-delivery-api-client)