Authentication Oauth2 flow
OAuth 2 is a protocol that allows a user to grant limited access to their resources on one site without having to expose their credentials. To read more about the OAuth2 protocol and understand more about token authentication, checkout this OAuth post written by AuthO team.
Example app
We highly recommend that you start with our example app to get started quickly. It uses Nuxt and an express server to handle the authentication.
https://github.com/storyblok/storyblok-app-example
Redirections
When the user opens a Storyblok sidebar app the system will redirect outside the iframe to the url defined in the app settings at "Url to your app". This redirect is necessary because of iframe security restrictions. When the user gets redirected and authenticated then you should redirect him to https://app.storyblok.com/oauth/app_redirect
via Javascript:
if (window.top == window.self) {
window.location.assign('https://app.storyblok.com/oauth/app_redirect')
} else {
// Example: this.loadStories()
}
OAuth2 authentication flow
Here we describe how the OAuth2 authentication flow works on Storyblok. First, we will show you where you get the access secret and client id tokens.
Get credentials
When you create an Application on Storyblok we will create these credentials for you. On the Application Edit form, the Client ID and Secret fields look like this:
Ask for permission
With your credentials already configured, the next step is to make a request to ask for permission fields in Storyblok. Below is a description of the following URL:
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
client_id: the client id credential
redirect_uri: the URL for redirect with the grant code
scope: a list of permissions to ask separated by space
state: an UUID
code_challenge: a string relates to code challenge method
code_challenge_method: code challenge method, can be 'plain' or 'SHA256'
The state, code_challenge and code_challenge_method are described in the following link.
When you make this request, the following page will be displayed:
Get the grant token
When the user approves your permissions, the Storyblok system will redirect the page for the following URL:
<YOUR_REDIRECT_URL>?code=<STORYBLOK_GRANT_CODE>&state=<YOUR_STATE_UUID>&space_id=<STORYBLOK_SPACE_ID>
redirect_url: the redirect URL that you configured in your application
code: a code generated by Storyblok for your app request the access and refresh tokens
state: the UUID state
space_id: the space the user allowed your application to access
Get access token
Now, in the redirect URL route, you must make a POST request to the following URL to get access and refresh tokens:
https://app.storyblok.com/oauth/token
The body request must be form url encoded with the following parameters:
grant_type: must be a string with 'authorization_code'
code: the grant code that comes from redirect
client_id: the client id
client_secret: the client secret
redirect_uri: the URL that will be used to receive the access and refresh tokens
The result of this request will be a JSON with the following structure:
{
"access_token": "<ACCESS_TOKEN>",
"refresh_token": "<REFRESH_TOKEN>",
"token_type": "bearer",
"expires_in": 899
}
Making authenticated requests
To authenticate requests to Storyblok API, you must add an 'Authorization' header with the 'Bearer <ACCESS_TOKEN>'.
Refreshing the access token
To refresh your token, you must make a form url encode request to the access token, but with other parameters described below:
grant_type: must be a string with 'refresh_token'
refresh_token: the refresh token
client_id: the client id
client_secret: the client secret
redirect_uri: the URL that will be used to receive the access and refresh tokens
The result of this request is the same of the get access token request, but without the refresh token field.
Getting user info
To get the currently logged in user and the space role you can send an authenticated GET request to the endpoint oauth/user_info
Example:
$ curl 'https://api.storyblok.com/oauth/user_info' -H 'authorization: Bearer YOURTOKEN'
This will return a user object and a array of space roles:
{
"user": {
"friendly_name": "My name",
"id": 20
},
"roles": [
{
"name": "admin"
}
]
}