App user connectors: let your users connect their own accounts

1. 1

   Register an OAuth application with the external service (like Google, Salesforce, or GitHub) you want to connect to.

   This tells the external service that your Lovable app is allowed to ask users for permission to access their data. You'll get details like a 'client ID' and 'client secret' from this step.

2. 2

   Make sure to add Lovable's special callback URL to your OAuth app settings: `https://connector-gateway.lovable.dev/api/v1/app-users/oauth2/callback`.

   This is how the external service sends users back to Lovable after they've given permission, so Lovable can securely handle the connection.

3. 3

   Go to the 'Connectors' section in your Lovable dashboard, find the service you want, and add a new 'client' using the details you got from registering your OAuth app.

   This sets up the basic connection between your Lovable workspace and the external service.

4. 4

   Link this new client to your specific Lovable project.

   This makes the connector available for use within that project.

5. 5

   If you want Lovable to use your own account for testing while you build, ask Lovable in the project chat to inspect or test something using your account, then approve the connection when prompted.

   This helps Lovable understand the external service's data and build the right integration for you, using your permissions.

6. 6

   In your project chat, tell Lovable what you want your users to do with their connected accounts, like 'Let my users connect their own Gmail so the dashboard shows their inbox.'

   This tells Lovable to add the necessary features to your app so users can connect their accounts and use the integration.

I want to let my users connect their own [External Service Name, e.g., Gmail or Salesforce] accounts. When they connect, I want my app to [describe what the app should do with their data, e.g., 'show their inbox' or 'display their open opportunities']. I have already registered an OAuth application with [External Service Name] and have the client ID and secret. Please guide me through setting this up.

OAuth application

This is like registering your app with an external service (like Google or Salesforce) to get a special ID and secret. It's how the service knows your app is legitimate and can ask users for permission to access their data.

Client ID and Secret

These are like a username and password for your app when it talks to an external service. The 'client ID' identifies your app, and the 'client secret' proves it's really your app.

Connector gateway

This is Lovable's secure system that handles all the technical details of connecting to other services. It keeps user passwords and access codes safe and makes sure your app can talk to the external service without you having to worry about security.

OAuth consent screen

This is the pop-up or page that an external service (like Google) shows to your users, asking them if they agree to let your Lovable app access their data and what permissions they are granting.

Tokens

These are like temporary digital keys that an external service gives to Lovable after a user grants permission. Lovable uses these keys to access the user's data on their behalf, without ever seeing their actual password.

Scopes

These are specific permissions that a user grants to your app, like 'read my emails' or 'view my calendar.' They define exactly what your app is allowed to do with the user's data on the external service.

Callback URL

This is a specific web address that an external service sends a user back to after they've given permission to your app. It's how Lovable knows the user has successfully connected their account.

Workspace identity reuse

For certain Lovable plans, this means if a user is already signed into your Lovable workspace, the app automatically knows who they are, so you don't need to add a separate sign-in system just for the app.

Offline access

This setting determines if your app can continue to act on a user's behalf even when they are not actively using the app, for things like background tasks or notifications.

• Forgetting to add Lovable's callback URL to your external service's OAuth app settings will prevent users from successfully connecting their accounts.
• Not having a way to identify individual users (like a sign-in system) in your app will prevent app user connectors from working correctly, unless you're on a Business or Enterprise plan using workspace identity reuse.
• Assuming your app can access all of a user's data; it can only access what the user explicitly grants through 'scopes' during the connection process.
• Not understanding the difference between a standard connector (one shared account) and an app user connector (each user's own account) can lead to building the wrong integration type.