Before you can request an access token, you’ll need to set up your server to handle the OAuth 2.0 flow. We recommend using JavaScript or Python, as we provide SDKs for these languages that can help simplify the authentication process.

Follow the below examples in Node.js or Python to help you create a server that can accept requests and communicate with the Webflow authorization server.

To enable users to install your App, you need to create an authorization link. This link directs users to a Webflow authorization screen where they can grant your App permission to access their Webflow data.

You can create the authorization link using various methods, with the recommended approach being through our JavaScript and Python SDKs.

Request Parameters

To create the authorization link, you will need the following information:

Constructing the authorization link

Using the SDK

To simplify the process of creating authorization links and handling OAuth flows, you can use the provided JavaScript and Python SDKs. These SDKs offer convenient methods to generate the authorization URL with the required parameters.

1
require('dotenv').config();
2
const express = require('express');
3
const { WebflowClient } = require('webflow-api');
4
5
const app = express();
6
const port = 3000;
7
8
// Endpoint to redirect to the authorization link
9
app.get('/auth', (req, res) => {
10
    const authorizeUrl = WebflowClient.authorizeURL({
11
        state: process.env.STATE,
12
        scope: 'sites:read',
13
        clientId: process.env.CLIENT_ID,
14
        redirectUri: process.env.REDIRECT_URI,
15
    });
16
17
    res.redirect(authorizeUrl);
18
});
19
20
app.listen(port, () => {
21
    console.log(`Server is running at http://localhost:${port}`);
22
});

https://webflow.com/oauth/authorize

https://webflow.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&scope=assets%3Aread%20assets%3Awrite%20authorized_user%3Aread%20cms%3Aread%20cms%3Awrite%20custom_code%3Aread%20custom_code%3Awrite%20forms%3Aread%20forms%3Awrite%20pages%3Aread%20pages%3Awrite%20sites%3Aread%20sites%3Awrite

Copy the link from the Dashboard

Additionally, you can copy an auto-generated installation link from your App’s settings.

In your Workspace Dashboard:

1. Select to “Apps and Integrations” in the left-hand menu
2. Scroll to the “App Development” section and find your App
3. Copy the link from the “Install” button

When users click on the authorization link, they will be taken to a screen where they can review and grant the necessary permissions for your App.

After the user authorizes the App, Webflow redirects them to your server using the redirect URI specified in your App settings. This GET request to your server includes the following query parameters:

• code - A single-use authorization code that you’ll exchange for an access token. This code is only valid for 15 minutes.
• state : optional - The unique state value you provided in the initial request. Ensure this value matches the original to protect against CSRF attacks.

Let’s set up an endpoint to handle the callback request and store these parameters, as you’ll need them in the next step to request an access token from Webflow.

See the example below for details on completing the following steps:

1. Setup the callback endpoint
   Create a route to handle the redirect from Webflow
2. Verify state parameter
   Optionally, check that the state parameter matches the one sent in the authorization request.
3. Extract authorization code
   Retrieve the code from the query parameters.

Example

1
require('dotenv').config();
2
const express = require('express');
3
const { WebflowClient } = require('webflow-api');
4
5
const app = express();
6
const port = 3000;
7
8
// Endpoint to redirect to the authorization link
9
app.get('/auth', (req, res) => {
10
    const authorizeUrl = WebflowClient.authorizeURL({
11
        state: process.env.STATE,
12
        scope: 'sites:read',
13
        clientId: process.env.CLIENT_ID,
14
        redirectUri: process.env.REDIRECT_URI,
15
    });
16
17
    res.redirect(authorizeUrl);
18
});
19
20
// Endpoint to receive info from the callback URL
21
app.get('/callback', async (req, res) => {
22
    const { code, state } = req.query; // Store code and state parameters as variables
23
24
    if (state !== process.env.STATE) {
25
        return res.status(400).send('State does not match');
26
    }
27
});
28
29
app.listen(port, () => {
30
    console.log(`Server is running at http://localhost:${port}`);
31
});

Now that you have the authorization code you can exchange it for an access token. The access token request should be made as soon as possible after authorization as an unconfirmed authorization code is only valid for 15 minutes.

Let’s walk through the steps to create a smooth flow for a user:

1. Request an access token from Webflow’s authorization server

   In the same endpoint we just set up, create a request to Webflow with the following parameters. Webflow requires these parameters to ensure that the entity requesting the access token is the same entity that received the authorization code.

   Authorization server endpoint

   POST https://api.webflow.com/oauth/access_token

   Request Parameters

   client_id

   stringRequired

   Unique ID for your application. Can be found in the dashboard.

   client_secret

   stringRequired

   Private value unique to your application. Can be found in the dashboard.

   code

   stringRequired

   Authorization code used to retrieve an access_token for the user. Can only be used once.

2. Store the access token securely

   For demonstration purposes, we’re storing the access token in a variable and printing it to the terminal. However, this approach is not secure for production. You should store the access token securely in a database or environment variables. For comprehensive guidance on securely storing tokens, please refer to our example apps on GitHub.

3. Redirect the user within your App

   After successfully obtaining the access token, redirect the user to an appropriate location within your app. This could be a dashboard, a welcome page, or any other relevant section. Ensure that the user experience is smooth and they are informed about the successful authentication.

Example

1
require('dotenv').config();
2
  const express = require('express');
3
  const { WebflowClient } = require('webflow-api');
4
  
5
  const app = express();
6
  const port = 3000;
7
  
8
  // Endpoint to redirect to the authorization link
9
  app.get( '/auth', (req, res) => {
10
      const authorizeUrl = WebflowClient.authorizeURL({
11
          state: process.env.STATE,
12
          scope: 'sites:read',
13
          clientId: process.env.CLIENT_ID, 
14
          redirectUri: process.env.REDIRECT_URI, // If the redirect URI is included in the auth link, it must also be included in the request for an access token
15
      });
16
  
17
      res.redirect(authorizeUrl);
18
  });
19
  
20
  // Endpoint to receive info from the callback URL
21
  app.get('/callback', async (req, res) => {
22
      const { code, state } = req.query;
23
  
24
      if (state !== process.env.STATE) {
25
          return res.status(400).send('State does not match');
26
      }
27
  
28
      try {
29
        // Request an access token
30
       const accessToken = await WebflowClient.getAccessToken({
31
            clientId: process.env.CLIENT_ID,
32
            clientSecret: process.env.CLIENT_SECRET,
33
            code: code,
34
            redirect_uri: process.env.REDIRECT_URI,
35
        });
36
  
37
        // Store the access token securely, e.g., in a database or session (not shown here for brevity)
38
      console.log(accessToken)
39
40
      // Redirect the user to your App
41
      res.redirect('/dashboard')
42
43
        
44
    } catch (error) {
45
        console.error('Error during OAuth process:', error);
46
        res.status(500).send('Internal Server Error');
47
    }
48
  
49
  });
50
51
    // Dashboard route for demonstraton purposes
52
    app.get('/dashboard', async (req, res) => {
53
        res.send('Welcome to your dashboard!')
54
    });
55
  
56
  app.listen(port, () => {
57
      console.log(`Server is running at http://localhost:${port}`);
58
  });
59
  

You’re ready to test your newly created authentication flow! In this step, we’ll start our server, navigate to the authorization screen, and get an access token from Webflow.

1. Create a secure tunnel using ngrok (OPTIONAL)

   using ngrok

   ngrok can be used to create a secure tunnel to your localhost, providing you with an HTTPS link that can be used as a valid redirect URI.

   1. Install ngrok Download and install ngrok using a package manager or directly from their website.

   Homebrew

   Choco

   $
   brew install ngrok/ngrok/ngrok

   2. Authorize the ngrok agent Copy your authentication token from ngrok, and enter the following command in your terminal.

   ngrok config add-authtoken $YOUR_AUTHTOKEN

   3. Create a secure tunnel In a new terminal window, run the following command to create a tunnel to your local server:

   ngrok http 3000

   Ngrok will provide you with a public HTTPS URL that forwards to your local server running on port 3000. It should look something like this:

   https://your-ngrok-url.ngrok.io

   4. Update your redirect URI in your App’s settings

   5. In your workspace settings, navigate to Apps & Integrations > App Development

   6. Find your App and click the “Edit App” button

   7. Navigate to the “Building Blocks” menu

   8. Update the Redirect URI with your Ngrok URL, ensuring that you include the correct endpoint. For example, if your endpoint is /callback, your Redirect URI should look something like https://your-ngrok-url.ngrok.io/callback.

   9. Update the redirect URI in your .env file Be sure to also update your redirect URI in your .env file if you’re passing your callback URI when creating an authorization link.

   REDIRECT_URI=https://your-ngrok-url.ngrok.io/callback

2. Start your server Enter the following command into your terminal to start your server.

   Node.js

   Python

   node server.js

3. Start the authorization flow

   1. Start the authentication process Open your browser and go to http://localhost:3000/auth. You will be redirected to Webflow’s authorization screen for your App.
   2. Authorize your app Select the workspace or sites you want your app to access, and click the “Authorize” button.
   3. Redirect to your app Upon successful authorization, you will be redirected to your app’s dashboard.
   4. Verify the access token Check your terminal to see the access token printed out.

Didn’t see what you expected? Read the troubleshooting guide below.

If your authorization link returns a 400 Bad Request error, ensure the following:

• The client_id is correct and matches the one provided in your app’s settings.
• The scopes you are requesting are registered and valid for your app in the dashboard.
• If you are including the redirect_uri parameter, verify that it matches the one registered for your app in the dashboard.
• Ensure that the URL is properly constructed and encoded if you are creating it manually.

• If you included a redirect_uri in your authorization link, you must also include it in your request for an access token.
• Ensure your environment variables are loading, and you’re sending the correct client_id and client_secret.
• Make sure you have a fresh code value, these tokens are single-use and can not be used again. Also, the token is only valid for 15 minutes after it has been granted.