Accessing Squarespace APIs using OAuth 2.0

Squarespace uses OAuth 2.0 to authorize third-party applications to integrate with Squarespace and consume Squarespace APIs.

Terms

Instructions

1. Register the client and obtain OAuth 2.0 credentials

Before a client can make Squarespace API calls, the client must be registered with Squarespace as an OAuth client. Submit the following information via this form.

• Client name
• Icon image (.png or .svg format, max size 200kb, 1:1 ratio)
• Redirect URI(s) - For example, https://thirdpartyapp.com/oauth/connect
• Initiate URL* - For example, https://thirdpartyapp.com/oauth/initiate.
• Link to Client’s Terms and Conditions
• Link to Client’s Privacy Policy

*Applies only to Squarespace partner apps. These will be linked from inside Squarespace.

We will review your registration and respond with your_client_id and your_client_secret as soon as possible. These credentials are used in the subsequent steps.

2. Prompt the user to authorize client access

The /authorize URL prompts the user to authorize client access to their Squarespace data and serves as the confirmation page. If a user selects Allow, OAuth 2.0 authentication is started between the client and Squarespace APIs. Append required and any optional parameters to the GET /authorize endpoint; all parameter values should be URL-encoded.

GET https://login.squarespace.com/api/1/login/oauth/provider/authorize

Authorize URL example with parameters

Note: Parameter values are in plain text and not URL-encoded for example purposes.

https://login.squarespace.com/api/1/login/oauth/provider/authorize?client_id=fGBjMDBaUHli&redirect_uri=http://localhost:8090/oauth/callback&scope=website.inventory,website.orders&state=2BsmGS9AAzFppUmcoIagOLj4iKII

3. Implement redirect URI

Both Allow or Deny on the confirmation page directs the user to the client redirect URI (i.e., the redirect_uri specified in Step 2) with query parameters appended by Squarespace. For Allow, the redirect URI should verify the state parameter and match it against state value that was appended for the /authorize endpoint. This verification prevents CSRF attacks. Squarespace doesn’t provide guidelines for Deny implementation.

4. Request access token

POST https://login.squarespace.com/api/1/login/oauth/provider/tokens

The client makes a POST /tokens call with required and any optional parameters for an access token from Squarespace. Access tokens in the response are only valid for 30 minutes. For more information, see Token expiration and long-term access.

Parameters

Example Response

{
  "token_type": "bearer",
  "access_token": "T1|Rr0Wc95uu3cSeBh06yB...",
  // expires 30 minutes after it’s created ...
  "access_token_expires_at": "1553532363.542",
}

5. Make API requests

After you obtain an access token, you can make API requests.

Endpoint:

https://api.squarespace.com/...

Authorization format:

Bearer<space><access-token-from-tokens-response>

Using the sample response from Step 4, Authorization would have the value:

Bearer T1|Rr0Wc95uu3cSeBh06yB...

Token expiration and long-term access

When a response from POST /tokens is received, access_token is only valid for 30 minutes. For long-term Squarespace API access, the client has to prompt the user to reauthorize using the GET /authorize endpoint or use refresh tokens.

Refresh tokens

To get a refresh token, add access_type=offline as a parameter to the GET /authorize request. When the client makes a POST /tokens call, the response includes refresh_token. Use the refresh token to get new tokens by making another POST /tokens call with the parameters below. The refresh token expires after seven days.

• grant_type=refresh_token
• refresh_token=<previous-refresh-token-value>

Note: Each POST /tokens call with a refresh_token parameter results in a new refresh_token and access_token. Refresh tokens are effectively one-time use—the original refresh token is invalidated as soon as the new access token is used. If long-term API access is required, the client should replace the stored refresh token with the most recent refresh_token. Note that obtaining new tokens doesn’t revoke existing access tokens.

Sample response from /tokens:

{
  "token": "T1|Rr0Wc95uu3cSeBh06yB...",
  "token_type": "bearer",

  // expires 30 mins after creation
  "access_token": "T1|Rr0Wc95uu3cSeBh06yB...",
  "access_token_expires_at": "1553532363.542",

  // expires 7 days after creation
  "refresh_token": "1|KYUYh35zcwzx4Zt/oty3...",
  "refresh_token_expires_at": "1554135363.542"
}

Sample use case with refresh tokens

Client has to poll orders from a user site indefinitely and needs to call the Squarespace API once per minute.

1. User authorizes client access to Squarespace APIs via confirmation page; client makes a POST /tokens call and obtains access and refresh tokens in response.
2. Client secures and stores the values below for current record (CR):

• access_token=<at-1>
• access_token_expires_at=<timestamp>
• refresh_token=<rt-1>

3. Prior to each API call, client checks if:

   CR.access_token_expires_at - currentTime > 10 seconds

   If true, client makes an API call with CR.access_token.

   If false, client makes a POST /tokens call with refresh_token=CR.refresh_token as a parameter for new access and refreshntokens; client stores new token values in CR:

   • access_token=<at-2>
   • access_token_expires_at=<timestamp>
   • refresh_token=<rt-2>

4. Client repeats Steps 2 and 3 indefinitely.

Invalid tokens and revoking access

Tokens become invalid in two ways: the tokens expire or the user revokes client access from the Squarespace UI. In either case, the user has to reauthorize client access to get new access tokens.

When an access token is invalid, Squarespace responds to API requests with 401 Unauthorized. If a client receives a 401, they should notify the user that their Squarespace integration requires reauthorization.