Use a Bubble App as an OAuth IdP (3rd Party OAuth / SAML Access)

Allow users on external apps (React app, Wordpress, Shopify, etc.) to log in using the same credentials as your Bubble app.

---

Vitals

Cost	Time	Difficulty
Free	30 minutes	Medium

Resources

Bubble Doc	YouTube Tutorial
https://manual.bubble.io/core-resources/application-settings/api#id-3rd-party-oauth-saml-access

---

Tutorial

Terminology

Term	Description
External App	The app you're authenticating (not built in Bubble).
Bubble App	Your Bubble project, which has 3rd Party OAuth/SAML access enabled (found in Settings > API).
OAuth User	A user logging into your external app through your Bubble app (must exist in your Bubble app's user table).

---

Adding a new client (external) app in Bubble

To add a new client app to your Bubble editor, navigate to Settings > API on the sidebar, then scroll to the section labeled 3rd Party OAuth / SAML Access. In this section, select a page where the end-user should be redirected to for login. The page selected here must contain a login form with a workflow that uses the action: Log the user in.

Once a login page is selected, click the "Add a new 3rd party app" button to create a new client app. Enter a name that describes this new client app, and enter the redirect URI for the client app.

A redirect URI is simply the URL that Bubble should direct the user to once they authenticate on the login page selected. This would be the URL of your external app where the code exchange will be handled.

Once you have created the client app in Bubble, you can continue wiith the authentication flow section of the tutorial.

OAuth Authentication Flow

This section covers how to integrate this tutorial in your client/external app. The exact steps may vary depending on the external infastructure, therefore, the following steps are broad and explain the general flow to be followed and the requests to be made for successful implementation.

Step 1: Authorization Request

Endpoint:

GET https://[APP_URL]/api/1.1/oauth/authorize

Query Parameters:

Key	Description
client_id	Found in your Bubble editor under API settings.
redirect_uri	The route in your external app where the code will be processed.

Behavior:

Redirects the user to the redirect_uri, appending a query string:

?code=YOUR_AUTH_CODE

---

Step 2: Exchange Code for Access Token

Endpoint:

POST https://[APP_URL]/api/1.1/oauth/access_token

Body Parameters (x-www-form-urlencoded):

Key	Description
client_id	From your Bubble editor.
client_secret	From your Bubble editor.
redirect_uri	Same as in Step 1. Typically a backend route.
code	The code returned in Step 1.

Returns (JSON):

{
  "access_token": "token_string",
  "expires_in": 86400,
  "uid": "bubble_user_id",
  "refresh_token": "refresh_token_string"
}

Response Details:

• access_token: Used for making authenticated API requests.

• expires_in: Token lifetime in seconds (default is 86400 = 24 hours).

• uid: The Bubble user's unique ID.

• refresh_token: Used to get a new access token after expiration.

---

Step 3: Refresh the Access Token

Endpoint:

POST https://[APP_URL]/api/1.1/oauth/access_token

Body Parameters:

Key	Description
client_id	From your Bubble editor.
client_secret	From your Bubble editor.
grant_type	Set to refresh_token.
refresh_token	The token obtained in Step 2.

Returns (JSON):

{
  "access_token": "new_token_string",
  "expires_in": 86400,
  "uid": "bubble_user_id",
  "refresh_token": "new_refresh_token_string"
}

---

Step 4 (Optional): Store Tokens Securely

It is recommended to store the following securely:

• access_token

• refresh_token

• uid

• expires_in

Use a secure backend or encrypted local storage based on your app’s architecture and security requirements.

---

Example: Fetch User Info from Bubble

After completing the integration, you can for example, fetch data from a user in your external app. This example explains what that would look like.

Go to Settings > API in your Bubble editor, enable the Data API, and make sure the User data type is selected.

Endpoint:

GET https://[APP_URL]/api/1.1/obj/user

Headers:

Authorization: Bearer [ACCESS_TOKEN]

Returns:

{
  "response": {
    "results": [
      {
        "email": "[email protected]",
        "_id": "bubble_user_id"
        // additional fields...
      }
    ]
  }
}

You can now use this user data inside your external application as needed.