Read our documentation about the OAuth2 flow on Storyblok
Creating a Storyblok Application
To create an application in Storyblok, you need to be a part of our Partner Program. In our Partner portal, you will see the Apps section on the left panel. After clicking the New button, you will see the following modal:
Fill out all of the required information (for now, only name and slug is necessary) and click on Save. After this, you will see a detail page for your App. On this page, access the Edit page to view the OAuth credentials and configure the URLs to your App. For now, store your Client ID and Client Secret credentials. Above, you can see where you will find these credentials:
Starting the API Development
For this tutorial we will use the grant package and the Koa library to develop our API and abstract some tasks in the OAuth2 workflow.
Setup the project
First, create a directory and start a project with:
We will use yarn, but you can use npm as well :)
Then, we will install the dependencies:
After, create an .env file to put your credentials. The .env file should look like this:
With the basic settings let's develop our app already authenticating with Storyblok using OAuth protocol.
Develop the Application
Setup initial code
Create a app.js file in the root folder on your project. Below is the initial code for this file:
After this, run the node app.js command in your terminal and open your browser at http://localhost:3000/. You will see a Server Started! message.
Setup grant for OAuth2 flow
The first step is to create a grant configuration and setup the callback route. Let's code:
Create a utils folder and put a factory-grant-config.js file in it. This file will export a factory function for the grant config.
After this, edit the app.js file to import the grant-koa package and the factory function. The code will be the following:
Now install your application on Storyblok space. After you install the application, open your browser in http://localhost:3000/connect/storyblok (this URL is explained in the documentation). Your browser will redirect to an authorization URL and open a page to request read and write approval in your space:
After approval, the browser will redirect to the callback route and will show the grant response data with the access and refresh tokens.
Recovering the space_id
When using the complete grant workflow, we don't have control of authorization and access routes. That's a problem because the access url redirects to the application with the space_id parameter in the URL. The space_id parameter is very important, so we need to make some changes in our backend to get and store the space_id in the session.
First, we need to change the redirect_uri variable on our .env file. Change this variable to http://localhost:3000/callback. Set the same URL on the Edit Application form on Storyblok in the "Oauth2 callback url" field.
After this, rewrite the callback route to get the code and space_id from authorizationURL and get the access and refresh tokens from access URL. Create a new file in utils folder called get-token-from-code.js. This file will contain the following content:
Then, edit the callback route to use this function to get access and refresh tokens:
Now that we have our settings ready, let's create the view that will be rendered in the App we created in Storyblok. First, create a folder called views , and inside it create two files, home.html and template.html.
In the home.html file, paste the code below:
And in the template.html file, paste the code below.
Let's add some logic to our front end. Create a public folder and an app.js file with our Vue.js application with the following code:
Now, in our backend, we need to create the routes for the CRUD.
Creating the CRUD routes
First, render the Home template when the application is authenticated. Edit the root route with the following code:
Then, edit the callback route to make a redirect to root route.
Add CRUD routes. First, create a function to instantiate the Storyblok JS client for us. Create a get-storyblok-client.js in utils folder with the following code:
Finally, add these CRUD routes:
Testing the CRUD app
Now that everything is ready, start the server and type in your terminal:
Open your browser in the http://localhost:3000/connect/storyblok URL. If everything goes as it should, you will be redirected to authentication. You should see a list of your stories in your space. An example is this:
Implementing the refresh token route
The last thing that we need to implement is the refresh token method. Add a new route with the following code:
In this tutorial, we learned how to build an application to Storyblok authenticating it with an OAuth2 protocol. We used the grant package and koa to build our backend. For the frontend, we used Vue.js to perform a full CRUD application. Remember that you can check the code at https://github.com/storyblok/storyblok-koa-oauth-example.
Working as frontend engineer at Storyblok. He loves contributing to the open source community and studies artificial intelligence in his spare time. His motto is "To go fast, go alone; to go far, go together".