OAuth 2.0 Authorization Flow

OAuth 2.0 allows Storyblok plugins to securely access resources by obtaining a Content Management API access token, specifically using the Authorization Code Grant Flow. This is facilitated with the @storyblok/app-extension-auth library in starter projects.

To create a new plugin, we highly recommend that you follow our getting started guide.

User Authorization

When users install a plugin, Storyblok redirects them to approve the plugin due to iframe restrictions. Once approved, the app is redirected back to the redirect_uri defined in the plugin settings. To ensure the plugin displays within an iframe in Storyblok, plugins should then redirect users back to Storyblok.

Space Plugin: https://app.storyblok.com/oauth/app_redirect
Tool Plugin: https://app.storyblok.com/oauth/tool_redirect

For example, when the component mounts, run the following code as a side effect:

if (typeof window !== 'undefined' && window.top === window.self) {
  window.location.assign('<https://app.storyblok.com/oauth/app_redirect>')
}

Authorization Request

Construct the authorization request URL using the following attributes:

client_id: Client ID of the app
redirect_uri: URL to redirect back to with the grant code
scope: Permissions such as read_content or write_content
state: Randomly generated value to prevent CSRF attacks
code_challenge and code_challenge_method: For PKCE, using SHA256

For example, the URL would look like:

<https://app.storyblok.com/oauth/authorize?client_id=><YOUR_CLIENT_ID>&response_type=code&redirect_uri=<YOUR_REDIRECT_URI>&scope=read_content write_content&state=<SOME_UUID>&code_challenge=<SHA_CODE>&code_challenge_method=S256

Authorization Response

After the user approves your plugin's permissions, Storyblok redirects to the specified URL with additional query parameters. The redirected URL will have the following structure:

{redirect_uri}?code={code}&state={state}&space_id={space_id}

The parameters provided in the URL are:

redirect_uri: The URL configured in your application settings as the redirect target.
code: A unique code generated by Storyblok for your application to request access and refresh tokens.
state: The exact value sent in the initial authorization request. This value is used to verify the request and prevent CSRF attacks.
space_id: The ID of the Storyblok space to which the user has granted access.

Upon receiving this response, retrieve the state value from the URL and compare it to the value you previously stored in a cookie. If the values match, proceed with approving the authentication response. If they don’t, deny the response to ensure security.

Access Token Request

After successful authorization, handle the redirect URI to retrieve the access token, selecting the endpoint based on the region:

EU region: https://app.storyblok.com/oauth/token
US region: https://app.storyblok.com/v1_us/token

To request the token, send a POST request with these attributes:

grant_type: authorization_code
code: Grant code from the redirect
client_id, client_secret, and redirect_uri

A successful response will return the following:

{
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "token_type": "bearer",
  "expires_in": 899
}

Note: In the redirect_uri request handler, determine the region of the space based on the spaceId. If the spaceId is less than 1,000,000, the space is located in the EU; otherwise, it is located in the US.

Token Refresh

To refresh an access token, send a POST request with the following attributes:

grant_type: refresh_token
refresh_token
client_id, client_secret, and redirect_uri

Retrieving User Info

To retrieve the logged-in user and their roles, make an authenticated GET request to the appropriate endpoint:

EU: https://api.storyblok.com/oauth/user_info
US: https://api-us.storyblok.com/oauth/user_info

A sample response will look like this:

{
  "user": { "friendly_name": "My name", "id": 20 },
  "roles": [{ "name": "admin" }]
}

Authenticated Requests to Storyblok API

Include the access token in the Authorization header when making API requests:

Authorization: Bearer <ACCESS_TOKEN>

This setup provides secure and controlled access to Storyblok plugins using OAuth 2.0, allowing access to the relevant API endpoints. For additional details on endpoints, refer to the Storyblok Management API documentation.

Related resources

App Bridge for Space and Tool Plugins