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.
User authorization
Section titled “User authorization”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");}Authorization request
Section titled “Authorization request”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=S256Authorization response
Section titled “Authorization response”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.
Access token request
Section titled “Access token request”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}Token refresh
Section titled “Token refresh”To refresh an access token, send a POST request with the following attributes:
grant_type:refresh_tokenrefresh_tokenclient_idandclient_secret
Use the token endpoint of the space’s region.
Retrieve user info
Section titled “Retrieve user info”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:
Authorization: Bearer <ACCESS_TOKEN>OAuth 2.0 gives plugins secure access to the Management API. For endpoint details, refer to the Management API documentation.
Related resources
Section titled “Related resources”Was this page helpful?
This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.
- Need help?Contact support (opens in a new window)
- Something isn’t right?Check system status (opens in a new window)
Get in touch with the Storyblok community