Skip to main content
Mapbox is a location platform for interactive maps, geocoding, routing, and static map images. The Mapbox connector lets your Lovable app render maps in the browser with Mapbox GL JS and call server-side Mapbox APIs through Lovable’s connector gateway. It’s designed for apps that need Mapbox-specific styles, Mapbox GL JS, or location features you want to run on Mapbox rather than another maps provider. With Mapbox, your app can:
  • Embed interactive maps with Mapbox GL JS using a public token
  • Geocode addresses and search places with the Geocoding API
  • Calculate routes and turn-by-turn directions
  • Render static map images for previews and thumbnails
For a quick prototype with generic maps, geocoding, or directions, Google Maps Platform can be faster to setup.

​
Common use cases and example apps

​
How to connect Mapbox

Who can create Mapbox connections depends on your plan and workspace settings. See Who can create connections. You can create multiple Mapbox connections using different tokens, which is useful for separating environments (for example, development and production) or using different Mapbox accounts. When the connection is created, you can link it to the projects where you want to use it. Anyone building in a project can ask Lovable in chat to link their project to it.

​
Prerequisites

Before connecting Mapbox, make sure you have:
  • A Mapbox account
  • At least one Mapbox access token: a public token (pk.) for browser maps, a secret token (sk.) for server-side APIs, or both
  • Permission to create connections in your Lovable workspace (see Who can create connections)
All Mapbox API usage counts toward your Mapbox plan and is billed by Mapbox, not Lovable.

​
Step 1: Get Mapbox access tokens

Mapbox uses two token types for different surfaces. They are not interchangeable.
  • Public token (pk.): browser only. Use it for Mapbox GL JS and map tiles in the frontend.
  • Secret token (sk.): backend only. Use it for geocoding, directions, static images, and every other server-side Mapbox API called through Lovable’s connector gateway.
Provide at least one token when you connect. Map-only apps can connect with a public token alone. Any server-side Mapbox feature requires a secret token on the connection. To create Mapbox access tokens:
1

Open your Mapbox account

Sign in to Mapbox.
2

Open access tokens

Go to Access tokens.
3

Create or copy tokens

Create the tokens your app needs:
  1. Public token: create or copy a default public token that starts with pk.. Restrict it to your app domains when you go to production.
  2. Secret token (if you need geocoding, directions, or other server-side APIs): click Create a token, give it a descriptive name (for example, Lovable integration), choose the scopes your app needs, and copy the token that starts with sk..
4

Store the tokens securely

Copy each token and store it securely. You’ll paste them into Lovable in the next step.
Your secret token functions like a password. Keep it secure, never embed it in frontend code, and never share it publicly.
See Mapbox documentation for details: Access tokens.

​
Step 2: Connect Mapbox to Lovable

You can create multiple connections using different tokens.
1

Open Mapbox in Connectors

Go to Connectors → App connectors and select Mapbox.
2

Add a connection

Click Add connection.
3

Configure the connection

  1. Display name: name the connection, for example Mapbox Prod. This name is only used inside Lovable to identify the connection.
  2. Secret token (optional): paste your secret token (sk.) if your app needs server-side geocoding, directions, static images, or other backend Mapbox APIs.
  3. Public token (optional): paste your public token (pk.) if your app renders Mapbox GL JS maps in the browser. This value is publicly visible in your published app after you link the connection to a project.
4

Choose who can use this connection

Under Who can use this connection, decide who in your workspace can use the connection. You start as the only person with access:
  • Only you (default): leave the access list as is; only you can use the connection and its associated data.
  • Invite specific people: add workspace members by email; only you and the people you add can use the connection and its associated data.
  • Invite entire workspace: click Invite entire workspace to make the connection available to everyone in your Lovable workspace.
See Who can manage connections for more information.
5

Connect

Click Connect. Lovable validates each token you provide against Mapbox before saving the connection.
When connected, anyone building in a project can ask Lovable in chat to link their project to Mapbox (based on configured connection-level access). Your Lovable apps can then render Mapbox GL JS maps with the public token and call server-side Mapbox APIs through Lovable’s connector gateway with the secret token.

​
Public and secret tokens

The connector accepts two tokens with different roles:
  • The secret token (sk.) is used for server-side Mapbox API calls. Lovable routes these requests through the connector gateway and exposes the token to your backend as MAPBOX_API_KEY after you link the connection to a project. Never use the secret token in frontend code.
  • The public token (pk.) is used for Mapbox GL JS in the browser. After you link the connection, Lovable exposes it as VITE_LOVABLE_CONNECTOR_MAPBOX_PUBLIC_TOKEN. Restrict this token to your app domains in the Mapbox account dashboard.
You must provide at least one token when creating the connection. Browser-only map apps can connect with a public token alone. Geocoding, directions, and other backend Mapbox features require a secret token on the connection. Server-side calls must go through Lovable’s connector gateway. Do not call https://api.mapbox.com directly from backend code in generated apps.

​
Limitations

The Mapbox connector cannot:
  • Use a public token (pk.) for server-side Mapbox API calls or through the connector gateway
  • Use a secret token (sk.) in frontend code or Mapbox GL JS
  • Replace domain restrictions on your public token. You must configure allowed URLs in the Mapbox account dashboard for production domains
  • Support per-end-user Mapbox authentication. Each connection represents a single Mapbox account shared across all projects linked to it
  • Refresh or rotate tokens automatically. To rotate, create new tokens in Mapbox and update the Lovable connection
If a token is revoked or deleted in Mapbox, reconnect the integration in Lovable with a valid token before API calls can succeed again. Editors and above can remove specific projects from a connection without deleting the connection entirely. The connection will remain available for other projects. To unlink projects:
1

Open Connectors

Open Connectors, then go to App connectors, and select .
2

Open the connection

Open the connection you want to manage.
3

Select projects

Under Linked projects, check the projects you want to unlink.
4

Confirm

Click Unlink projects and confirm.
When unlinked, those projects will no longer have access to through this connection. If a project needs again, you can link it to any available connection.

​
How to delete a connection

Workspace admins and owners can delete connections. Other members can delete a connection if they created it, or if they have been explicitly granted access to it.
Deleting a connection is permanent and cannot be undone. It will remove the credentials from all linked projects, and any apps using this connection will stop working until a new connection is added.
Before deleting, review the Linked projects section to see which projects are currently using the connection. To delete a connection:
1

Open Connectors

Open Connectors, then go to App connectors, and select .
2

Open the connection

Open the connection you want to remove.
3

Review linked projects

Review the Linked projects section.
4

Delete

Under Delete this connection, click Delete and confirm.