Skip to content

OAuth 2.0 Authorization Flow

OAuth 2.0 allows Storyblok plugins to securely access resources by obtaining a Management API access token, specifically using the Authorization Code Grant Flow. The starter projects implement this flow with the @storyblok/app-extension-auth library.

When users install a plugin, Storyblok asks them to approve the plugin. Next, it redirects them back to the redirect_uri defined in the plugin settings. To ensure the plugin displays within an iframe in Storyblok, plugins need to 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");
}

Construct the authorization request URL using the following attributes:

Parameter Description
client_id The app’s client ID.
response_type Set to code.
redirect_uri The URL to redirect back to with the grant code.
scope Set to read_content or write_content. The user grants the permissions on the consent screen.
state A randomly generated value that prevents cross-site request forgery (CSRF) attacks.
code_challenge and code_challenge_method Parameters for proof key for code exchange (PKCE) using SHA256.

For example, the URL looks like this:

https://app.storyblok.com/oauth/authorize?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&scope=read_content%20write_content&state={state}&code_challenge={code_challenge}&code_challenge_method=S256

After the user approves your plugin’s permissions, Storyblok redirects to the specified URL with additional query parameters.

The redirected URL has the following structure:

{redirect_uri}?code={code}&state={state}&space_id={space_id}
Parameter Description
redirect_uri The URL configured in your plugin settings as the redirect target.
code A unique code that Storyblok generates for your plugin to request access and refresh tokens.
state The exact value sent in the initial authorization request. Your plugin uses this value to verify the request and prevent CSRF attacks.
space_id The ID of the space the user granted access to.

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. Otherwise, deny the response.

After successful authorization, request the access token in the redirect URI handler. Use the endpoint that matches the space’s region:

  • EU: https://api.storyblok.com/oauth/token
  • US: https://api-us.storyblok.com/oauth/token
  • CA: https://api-ca.storyblok.com/oauth/token
  • AP: https://api-ap.storyblok.com/oauth/token
  • CN: https://app.storyblokchina.cn/oauth/token

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

Parameter Description
grant_type Set to authorization_code.
code The grant code from the redirect.
code_verifier The PKCE verifier you used to create the code_challenge.
client_id The plugin’s client ID.
client_secret The plugin’s client secret.
redirect_uri The URL to redirect back to with the grant code.

A successful response returns the following:

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

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

  • grant_type: refresh_token
  • refresh_token
  • client_id and client_secret

Use the token endpoint of the space’s region.

To retrieve the logged-in user, space, and roles, send an authenticated GET request to the user info endpoint that matches the space’s region:

  • EU: https://api.storyblok.com/oauth/user_info
  • US: https://api-us.storyblok.com/oauth/user_info
  • CA: https://api-ca.storyblok.com/oauth/user_info
  • AP: https://api-ap.storyblok.com/oauth/user_info
  • CN: https://app.storyblokchina.cn/oauth/user_info

A sample response looks like this:

{
"user": { "id": 20, "email": "user@example.com", "friendly_name": "My name" },
"space": { "id": 12345, "name": "My space" },
"roles": [{ "name": "admin" }]
}

Authenticated requests to the Storyblok API

Section titled “Authenticated requests to the Storyblok API”

When making API requests, include the access token in the Authorization header:

Terminal window
Authorization: Bearer <ACCESS_TOKEN>

OAuth 2.0 gives plugins secure access to the Management API. For endpoint details, refer to the Management API documentation.

Was this page helpful?

What went wrong?

This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.