Square Seller Authorization (OAuth)

This Bubble.io plugin will allow you to request authorization and obtain access tokens using OAuth from other Square seller accounts so that your app can manage their Square resources and payments.

Square API Reference Documentation

Forum: Help - Feedback - Feature Requests

[New Plugin] Square OAuth - By InterwebbBubble Forum

Plugin Page: Purchase - Ratings

Square OAuth Plugin for Bubble, by InterwebbBubble

Please Note: This plugin has very important app security guidance.

Key Concepts

OAuth Flow

OAuth is a common way for an app to get authorization to another app using tokens, It has a specific step-by-step flow:

Authorize - your app opens an external URL to the authorization page of a users Square seller account. You define which scopes (permissions) you are requesting and for the user to authorize your app to have access to.
Obtain a Token - your app makes an API call to the users Square seller dashboard using a unique Authorization Code from the previous step to request an Access Token. An Access Token and Refresh Token are returned.
Refresh the Token - your app makes an API call to the users Square seller dashboard using the Refresh Token from the previous step to request a new Access Token.

Scopes

Scopes are the permissions that are being requested and authorized by the user. The specific scopes required for each API request can be found within the Square OAuth Permissions Reference.

Tokens

Access Token - The OAuth bearer token used in your backend workflow actions so that any Square plugin action will run against the Square seller account to which the Token is connected. The token will automatically expire after 30 days and will not work after that time period so it will need to be refreshed.

Generally, we describe the Access Token from your own Square app in your developer dashboard as a Personal Access Token, which would be entered in the plugin page of your Bubble app, and the Access Token obtained via OAuth as an OAuth Access Token used in the Access Token (OAuth) field of the plugin's actions.

Refresh Token - The refresh token is used in a repeat of the Obtain a Token step to obtain a new Access Token before the previous token expires.

Security

Important

Access Tokens are highly sensitive and should be treated in the same way as passwords. Please adhere to the following best practices:

Workflow actions run using an OAuth Access Token should only be run as a backend workflow (server-side) so that their data is not exposed to the user's client/browser.
It is recommended that you refresh Access Tokens every 7 days. This can be done using a scheduled API workflow. Please see our demo for an example.
Set privacy rules in your database so that no users have access to the stored tokens.
Keep your app's scopes to the lowest level of privilege that is required. For example, if you do not need to manage customer profiles, do not use the Square Customers API scopes when creating an Authorize URL.
Ideally, you should encrypt and obfuscate tokens stored in the database so that even administrators cannot know or access them.

Getting Set Up

In the Square developer dashboard

Add the OAuth Application Id and Application Secret from your Square developer dashboard to the plugin page in your app.
Add a Redirect URL to the Square Developer Dashboard OAuth page. The URL needs to exactly match the URL of the page in your app where you request authorization from your user. For Example: https://interwebbplugins.co.uk/authorize_page

In your Bubble app - Authorize

On the page you have created to run your authorization workflows (your Redirect URL page), use a Button to trigger the Create Authorize URL workflow action and then Open External URL to open the Authorize URL from the previous step.
The user will be sent to Square to authorize the permissions your app has requested (See the permissions reference here.) with their Square Seller account. Once authorized, they will be returned to your Bubble apps authorization page with the Authorization Code as a URL Parameter.

In your Bubble app - Obtain a Token

Create a workflow that only runs when your app's authorization page has an Authorization Token as a parameter in the URL.
Using the code returned from your Authorization step, in the same workflow, run the Obtain Token workflow action and save the returned Access Token, Refresh Token, Expires At date and Merchant Id securely in your database.
The Initial Access Token will expire after a time period (30 days) and so it will need to be regularly regenerated using the Refresh Token. To regenerate the Access Token, set up a scheduled backend workflow to run the Obtain Access Token workflow action with the Use Refresh Token field checked and replace the Access Token in your database before the Expires At date.

Use the OAuth Access Token in your workflows

When running a workflow action from another Square plugin, remove the Personal Access Token from the plugin's page in your app as this will be prioritised over the OAuth Access Token in the action's fields.
As actions using OAuth Access Tokens need to be run as a backend workflow for security reasons, you have two options to display the data to the user:
1. Save the workflow actions returned values to the database and display database values to your user.
2. Use the API Connector plugin to call your own backend workflows and display the returned values from the Square plugin workflow action.

Examples

Please see our Square OAuth demo via the bubble editor for examples of how we have set up Square OAuth.

Workflow Actions

Create Authorize URL

Creates a URL that opens to the authorization page of your user Square seller account. The user needs to be signed into the Seller account before the URL is opened.

Obtain Access Token

Obtains an Access Token using either the code returned from the Authorize URL or using a Refresh Token from a previous Obtain Access Token workflow action.