How to use Mapbox securely

Mapbox is critical infrastructure for our customers. We go to great lengths to protect the security of your account, your data, and your users. This guide contains recommendations and resources for building secure applications, keeping your account secure, and where to go to learn more about security at Mapbox.

Build secure applications

There are a few guidelines you can follow to build more secure applications with Mapbox.

Access tokens

Manage scopes. Each access token you create will have a set of permissions that allow you to make certain types of requests to Mapbox APIs — these are called scopes. Here are some best practices for access token scopes:

  • A client application (for example, a web application running in your browser) should only use a token with public scopes. Public tokens have read-only access rights to styles.
  • All requests requiring a token with secret scopes should be made on a server. Secret token API requests should never be exposed to the client.
  • If you need to do potentially sensitive operations in the client (for example, uploading new data or deleting styles) use the Mapbox Tokens API to generate a temporary token for the specific workload.
  • To protect your account and your data, do not grant more scopes than necessary to each token. For example, if you are creating a token to upload data to Mapbox with the Mapbox Uploads API, you will want to make sure you select the uploads:write and uploads:read scopes. To display a map in a web or mobile application, you should create a separate access token that does not include the secret uploads-related scopes, but does include the public styles:read and fonts:read scopes.

Rotate tokens. Any public access tokens you include in a web page will be visible to anyone who makes an effort to look for it. Access tokens, however, can be deleted and rotated at any time if you suspect misuse. Here are some tips for managing and rotating access tokens:

  • Store tokens in environment variables or application configurations on your server.
  • Generate separate tokens for each application you build. This will make it easier to track usage and identify unexpected activity.
  • Use the Mapbox Tokens API to rotate tokens on a schedule.

Keep tokens private. In open source iOS applications, access tokens can be further protected to prevent abuse by other developers:

Token analytics. Keeping track of token-specific analytics will help you identify any unexpected usage. Here are some suggestions for tracking usage by access token:

Data security

There are different privacy and security settings for different assets within your Mapbox account. Understanding privacy details will help you make the best decision for your situation.

Tilesets. Tilesets are public by default. Tilesets can only be made private by users on Commercial or Enterprise plans. Here are some details about public and private tilesets:

  • Public tilesets: Public tilesets can be used by any Mapbox user’s access token. But another user will need the map ID for your tileset to use it with their access token. No central, publicly accessible repository of tilesets exists. If you expose a map ID for a public tileset in your client-side code, another Mapbox user could use your tileset, but they would not be able to edit it.
  • Private tilesets: Users with a Commercial or Enterprise plan can restrict the tilesets you upload to your Mapbox account so they can only be loaded with an access token from the owner of the tileset’s account. This means that other users cannot use their access tokens to access your tilesets.

Styles. Styles can be made public or private by users regardless of plan level. When a style is created, it is private by default. Here are some details about public and private styles:

  • Public styles: If a style is public, the style URL can be used by any Mapbox user with their access token. But only the owner of a style can make changes or delete a style, even if it’s public.
  • Private styles: If a style is private, the style URL can only be used with an access token from the the owner’s account.

CSP Directives

As a mitigation for Cross-Site Scripting and other types of web security vulnerabilities, you may use a Content Security Policy (CSP) to specify security policies for your website. If you do, Mapbox GL JS requires the following CSP directives:

child-src blob: ;
img-src data: blob: ;
script-src 'unsafe-eval' ;

Requesting styles from Mapbox or other services will require additional directives. For Mapbox, you can use this connect-src directive:

connect-src https://*.tiles.mapbox.com https://api.mapbox.com

Mapbox GL JS popups

Developers shouldn’t allow users to provide arbitrary data (or “untrusted content”) to popups using setHTML. This method does not include HTML filtering or sanitization, and must be used only with trusted content. Use setText instead for security against XSS if the popup content is user-provided.

API requests

When retrieving TileJSON metadata with the Maps API, use the ?secure parameter to request resources in the response as HTTPS endpoints.

Review security bulletins

For recent security issues related to all Mapbox products, please see our Security bulletins page.

Keep your account secure

Keep your Mapbox account secure to protect your data, billing information, and other profile information.

Strong passwords

Use a strong password to keep your account secure. Keep passwords secret, don’t reuse passwords between accounts, and use complex passwords. Consider using a password manager for your Mapbox account.

Two-factor authentication

You can also set up two-factor authentication for your Mapbox account. Two-factor authentication, also known as multi-factor authentication (MFA) or two-step authentication, provides an optional, but recommended, layer of security to your account. Once enabled, you’ll be prompted to enter your password as well as a security code generated by an authentication app on your mobile device whenever you log in. We recommend using Google Authenticator — it’s free and available for iOS and Android. For a Windows phone, use the Authenticator app.

To learn how to enable two-factor authentication for your account, see the security section of our Account FAQ.

A recovery code is a single-use code that lets you sign in without your two-factor device. This code will help you gain access to your account in the event that you lose or replace your two-factor device. To use the code, you’ll need your username or email and your password. Find instructions for using a recovery code in our Account FAQ: How do I use a recovery code?

Learn about our bug bounty program

Mapbox appreciates the effort of software security researchers who work to make the Internet more secure. Our security vulnerability coordination and bug bounty program exist to reward the work of security researchers who find issues with our software and web services.

Learn about or report a security issue to our bug bounty program.