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"
    }
  ]
}