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 appredirect_uri
: URL to redirect back to with the grant codescope
: Permissions such asread_content
orwrite_content
state
: Randomly generated value to prevent CSRF attackscode_challenge
andcode_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 redirectclient_id
,client_secret
, andredirect_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
, andredirect_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.