Authorization

Make authenticated requests to the Webflow API

🚧

Introducing Scopes!

In the latest version of our REST API, we've introduced scopes, which define the specific permissions an app will have. Scopes will ensure our users have more control over the data an application can access on their behalf, and the actions it can take.

Learn more about how to request the correct scopes for your application in our Scopes Guide.

Overview

Authentication is the digital identity checkpoint to verify who you are online. Authorization follows authentication. Once granted authenticated access to Webflow's API, what you're allowed to do depends on your authorization.

OAuth 2.0, which is what we use to authenticate and authorize 3rd-party applications, offers a way securely authenticate your App and authorize its actions, without needing sensitive information like their password or API Key.

Webflow supports the authorization code grant flow, which upon successful completion, grants a scoped access_token. Access tokens allow apps to make requests to Webflow's APIs, on behalf of an authorized user, whereas scopes define the specific permissions an app will have.

Why is authorization important?

  • Security: It's a front-line defense against cyber threats. Authorized users only, please!
  • Data Integrity: By regulating access and actions, we maintain data reliability.
  • Compliance: Securing user data isn't just smart, it's often required in order for users from larger entities - like enterprises and government organizations - to even use your app.

Authorization steps

To get authorized access to Webflow's API on behalf of yourself or another authorized user, you'll need to follow the following steps:

  1. Registering your App and it's permissions (scopes) with Webflow
  2. Request authorization from a user to secure an authorization code
  3. Get your access token and make an authenticated request
  4. Revoke Access, If Needed

The guide below will quickly walk through these steps in detail. To get started even faster, using one of our example apps, check out out Quick Start Guide.


Step 1. Register Your App

To register an application to your Workspace, navigate to your desired Workspace in your dashboard. Then, access your Workspace settings by clicking the gear icon to the right of your Workspace name. In your workspace settings, navigate to the "Integrations" pane and scroll to the "App Development" section.

Click, the "Create an App" button.

This will display a modal asking you to enter details about your new App. The following information is required for registration:

FieldsDescription
Application NameThe name of the application that will appear when someone authorizes your application.
Application DescriptionA short description that will appear to users on the authorization request page.
Redirect URLThe URL we redirect users to after they approve / deny the authorization request. URL must begin with https and served with SSL.
Application HomepageA link to the homepage of your application.

After entering your App details, press "Continue." You'll be asked to determine your App's capabilities. Toggle "Data Client" as capability for your app.

Here you'll register your App's scopes, which will determine the resources you app will be able to access.

πŸ“˜

Introducing Scopes

In the latest version of our REST API, we've introduced scopes, which define the specific permissions an app will have. Scopes will ensure our users have more control over the data an application can access on their behalf, and the actions it can take.

app-capabilities

After successful registration, you should see your App details in the Workspace Applications section of your integrations tab, including the client_id and client_secret tokens for your application. You will need these in order to request an authorization_code and access_token for users of your application.

Step 2. Request Authorization

Request

In order for a user to authorize your app, you'll need to direct the user to Webflow's authorization URL using the parameters below. When the user authorizes your app, they will be redirected back to the redirect URL provided during App registration.

Request Endpoint

GET https://webflow.com/oauth/authorize

πŸ“˜

Note the domain for this endpoint uses webflow.com while all other requests are made to api.webflow.com.

Request Parameters

ParameterDescription
client_idUnique ID for your application. Can be found in the dashboard
response_typeThis value should always should be code
scopeInclude the scopes your app needs. Request your scopes using the following format - resource:access_level | e.g. assets:read
redirect_uri
optional
The URI to redirect the user once they've granted authorization. This must match what's used in your App settings.
state
optional
A token value provided by your application for CSRF protection. Check out this article to learn about state parameters.

With all parameters included, your request should look like the following example, though substituted with your own client_id , scopes, and optional state parameters:

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

This URL will direct the user to an authorization screen, where they can grant permissions to select sites and workspaces for your app.

Response

Once the user authorizes your app, Webflow will send the user to the redirect URI provided during app setup with additional parameters as a response. You can change the redirect URI at anytime in the dashboard.

Response Parameters

ParameterDescription
codeAuthorization code that will be used to retrieve an access_token for the user. This code can only be used once.
state
optional
Same as the original value if provided.

If we were using my-app.com/auth as the redirect URI, the response would look like the below example, though substituted with a unique code and optional state parameters.

https://myapp.com/auth?code=a3bddff3d52998...b49acf21c5e2500&state=xyzABC123

If you choose to pass a state parameter, your app should compare the state parameter it receives from the redirect URI with the state parameter it originally provided to the authorization URI. If there is a mismatch, your app should reject the request and stop the authentication flow.

Error Response Parameters

If the user does not accept your request or if an error has occurred, the response query string contains the following parameters:

ParameterDescription
state
optional
Same as the original value if provided.
errorAn error code specifying which error occurred.
error_descriptionHuman readable description of the error that occurred.

Step 3. Get Access Token and Make a Request

Now that we have an authorization_code we can use it to request an access_token, which we'll use to make authenticated requests to the API.

The access_token request should be made as soon as possible after authorization as an unconfirmed authorization_code is only valid for 15 minutes.

Request Endpoint

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

Request Parameters

ParameterDescription
client_idUnique ID for your application. Can be found in the dashboard
client_secretPrivate value unique to your application. Can be found in the dashboard
codeAuthorization code used to retrieve an access_token for the user. Can only be used once.
grant_typeShould always be authorization_code
redirect_URI
optional
This URI must match the URI in your App details.

Response

Response Parameters

ParameterDescription
token_typeWill always be "bearer"
access_tokenToken to use when making API requests on behalf of a user

Error Response

ParameterDescription
errorAn error code specifying which error occurred.
error_descriptionHuman readable description of the error that occurred.

Step 4. Revoke Authorization

You may want to allow users to revoke authorization within your app. In that case, you would send a request to the following endpoint.

Request

Request Endpoint

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

Request Parameters

ParameterDescription
client_idUnique ID for your application. Can be found in the dashboard
client_secretPrivate value unique to your application. Can be found in the dashboard
access_tokenToken received on a previous authorization flow

Response

Response Parameters

ParameterDescription
didRevokeBoolean. True on successful revocation

Error Response

ParameterDescription
errorAn error code specifying which error occurred.
error_responseHuman readable description of the error that occurred.

OAuth Errors

Authorization Errors

Errors are returned in the query-string to the redirect URL setup for your application

ParameterDescription
invalid_requestmissing or invalid client_id
unsupported_response_typeresponse type given was not code
access_deniedUser did not complete or allow authorization

Access code errors

Errors are returned by the API for the POST /oauth/access_token endpoint

ParameterDescription
unsupported_grant_typegrant_type should always be specified as the string authorization_code
invalid_clientNo application found matching the provided credentials
invalid_grantProvided code was invalid