---
title: OAuth 2.0 Authorization Flow
description: Discover Storyblok's documentation with comprehensive developer guides, user manuals, API references, and examples to help you get the most out of the headless CMS platform.
url: https://storyblok.com/docs/plugins/oauth-authorization-flow
---

# 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](https://www.rfc-editor.org/rfc/rfc6749#section-4.1). This is facilitated with the `@storyblok/app-extension-auth` library in [starter projects](https://github.com/storyblok/space-tool-plugins).

## 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:

```javascript
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 app
-   `redirect_uri`: URL to redirect back to with the grant code
-   `scope`: Permissions such as `read_content` or `write_content`
-   `state`: Randomly generated value to prevent CSRF attacks
-   `code_challenge` and `code_challenge_method`: For PKCE, using SHA256

For example, the URL would look like:

```bash
<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:

```bash
{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 redirect
-   `client_id`, `client_secret`, and `redirect_uri`

A successful response will return the following:

```json
{
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "token_type": "bearer",
  "expires_in": 899
}
```

> [!TIP]
> **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`, and `redirect_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:

```json
{
  "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:

```bash
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](https://www.storyblok.com/docs/api/management).

## Related resources

[App Bridge for Space and Tool Plugins](/docs/plugins/app-bridge)

[OAuth Guide by Auth0](https://auth0.com/docs/get-started)

[The OAuth 2.0 Authorization Framework (RFC)](https://tools.ietf.org/html/rfc6749)

## Pagination

-   [Previous: App Bridge for Space and Tool Plugins](/docs/plugins/app-bridge)
-   [Next: Introduction](/docs/plugins/field-plugins-legacy)