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:write
anduploads: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 publicstyles:read
andfonts:read
scopes.
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.