How to use Mapbox securely
Mapbox is critical infrastructure for our customers. We work hard 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
Avoid using the default public token. The default public token in your account does not allow for additional security features such as scope management and URL restrictions. Generate a new public token to use these security features.
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.
- Make all requests requiring a token with secret scopes 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:writeanduploads:readscopes. 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 publicstyles:readandfonts:readscopes.
Enable URL restrictions. You can add URL restrictions to a token to help prevent abuse of billable API endpoints with your token. When you define a token's allowed URLs, that token will only work for requests that originate from the URLs you specify. Tokens without restrictions will work for requests originating from any URL. This feature is compatible with versions of Mapbox GL JS 0.53.1 and greater.
Isolate tokens. Generate a separate access token for each application you build. This will make it easier to track usage and identify unexpected activity.
Rotate tokens. Any public access tokens you include in a webpage will be visible to anyone who makes an effort to look for it. Access tokens 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.
- Use the Mapbox Tokens API to rotate tokens on a schedule.
Keep tokens private. In open source iOS and Android applications, access tokens can be further protected to prevent abuse by other developers:
- Avoid having access tokens in your open source iOS project's GitHub repository by making them private using Xcode.
- Avoid having access tokens in your open source Android project's GitHub repository by using a Gradle script.
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:
- Use the Statistics page to browse account usage or usage for a specific access token for a week, month, year, or custom date range.
- Deploy distinct tokens for each of your applications, which enables you to isolate statistics by tokens for more granular usage tracking.
Data security
There are different privacy and security settings for different assets within your Mapbox account. Understanding privacy details will help you make the right decision for your situation.
Tilesets. You can make tilesets public or private. When you create a tileset, it is private by default. 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 tileset ID for your tileset to use it with their access token. No central, publicly accessible repository of tilesets exists. If you expose a tileset 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: If a tileset is private, the tileset ID can only be used with an access token from the owner's account. This means that other users cannot use their access tokens to access your tilesets.
Styles. You can make styles public or private. When you create a style, 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 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 and you are using Mapbox GL JS, use the CSP directives listed in the Mapbox GL JS documentation.
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 Mapbox Tiling Service (MTS), use the ?secure parameter to request resources in the response as HTTPS endpoints.
Review product security information
For more information about security practices at Mapbox, see our Security 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, which is 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 documentation.
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 documentation
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