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:
- Registering your App and it's permissions (scopes) with Webflow
- Request authorization from a user to secure an authorization code
- Get your access token and make an authenticated request
- 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:
| Fields | Description |
|---|---|
| Application Name | The name of the application that will appear when someone authorizes your application. |
| Application Description | A short description that will appear to users on the authorization request page. |
| Redirect URL | The URL we redirect users to after they approve / deny the authorization request. URL must begin with https and served with SSL. |
| Application Homepage | A link to the homepage of your application. |
| Installation Preference | A toggle indicating whether your app should be installed to a single site or multiple sites. |
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.
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.comwhile all other requests are made toapi.webflow.com.
Request Parameters
| Parameter | Description |
|---|---|
client_id | Unique ID for your application. Can be found in the dashboard |
response_type | This value should always should be code |
scope | Include the scopes your app needs. Request your scopes using the following format - resource:access_level | e.g. assets:read |
redirect_urioptional | The URI to redirect the user once they've granted authorization. This must match what's used in your App settings. |
stateoptional | 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 multiple sites or a single workspace for your app. If you've restricted your app to only be installed to a single site, users will only be able to select one site.
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
| Parameter | Description |
|---|---|
code | Authorization code that will be used to retrieve an access_token for the user. This code can only be used once. |
stateoptional | 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:
| Parameter | Description |
|---|---|
stateoptional | Same as the original value if provided. |
error | An error code specifying which error occurred. |
error_description | Human 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
| Parameter | Description |
|---|---|
client_id | Unique ID for your application. Can be found in the dashboard |
client_secret | Private value unique to your application. Can be found in the dashboard |
code | Authorization code used to retrieve an access_token for the user. Can only be used once. |
grant_type | Should always be authorization_code |
redirect_URIoptional | This URI must match the URI in your App details. |
Response
Response Parameters
| Parameter | Description |
|---|---|
token_type | Will always be "bearer" |
access_token | Token to use when making API requests on behalf of a user |
Error Response
| Parameter | Description |
|---|---|
error | An error code specifying which error occurred. |
error_description | Human 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
| Parameter | Description |
|---|---|
client_id | Unique ID for your application. Can be found in the dashboard |
client_secret | Private value unique to your application. Can be found in the dashboard |
access_token | Token received on a previous authorization flow |
Response
Response Parameters
| Parameter | Description |
|---|---|
didRevoke | Boolean. True on successful revocation |
Error Response
| Parameter | Description |
|---|---|
error | An error code specifying which error occurred. |
error_response | Human 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
| Parameter | Description |
|---|---|
invalid_request | missing or invalid client_id |
unsupported_response_type | response type given was not code |
access_denied | User did not complete or allow authorization |
Access code errors
Errors are returned by the API for the POST /oauth/access_token endpoint
| Parameter | Description |
|---|---|
unsupported_grant_type | grant_type should always be specified as the string authorization_code |
invalid_client | No application found matching the provided credentials |
invalid_grant | Provided code was invalid |