Mapbox Authentication: Access Tokens & API Security (2026)

Authentication overview

Authentication for Mapbox APIs and SDKs primarily relies on access tokens. These tokens are unique, alphanumeric strings that identify your application and authorize its requests to Mapbox services. Each token is associated with specific scopes, which define the permissions granted to that token, such as reading map styles, geocoding addresses, or accessing navigation data. This granular control allows developers to issue tokens with only the necessary permissions, adhering to the principle of least privilege.

Mapbox employs two main types of access tokens to accommodate different application architectures:

• Public Tokens (Client-side): These tokens are designed for use in client-side applications (e.g., web browsers, mobile apps) where the token might be exposed. They are typically restricted to read-only access for services like map display, geocoding, and routing. Public tokens are associated with specific domain restrictions or package IDs to enhance security.
• Secret Tokens (Server-side): Intended for server-side or backend applications, secret tokens should never be exposed in client-side code. They can be granted broader permissions, including write access for services like Mapbox Studio uploads or managing private datasets. Secret tokens offer higher security but require diligent handling to prevent compromise.

All requests to Mapbox APIs must include a valid access token. The method of inclusion varies depending on the specific API or SDK being used, but commonly involves passing the token as a query parameter or an HTTP header.

Supported authentication methods

Mapbox's authentication strategy is centralized around access tokens, which function as bearer tokens. OAuth 2.0, a standard for delegated authorization, is not directly exposed as a primary authentication flow for individual API requests in the same manner as some other platforms, but the fundamental concept of using scoped tokens for access control aligns with OAuth principles. For more on OAuth's role in API security, see the OAuth documentation.

The choice between a public and secret token depends on the application's architecture and the specific Mapbox services being accessed. Developers should always use the token type with the minimum necessary permissions for the task at hand.

Getting your credentials

Mapbox access tokens are managed through the Mapbox Account Dashboard. Follow these steps to generate and configure your tokens:

1. Sign Up or Log In: Navigate to the Mapbox Account page and create a new account or log in to an existing one.
2. Access Tokens Page: From your account dashboard, go to the Access tokens section. You will typically see a default public token already generated for you.
3. Create a New Token: Click the "Create a token" button.
4. Name Your Token: Provide a descriptive name for your token (e.g., "My Web App Production" or "Backend Data Processing").
5. Configure Scopes: Select the necessary scopes for your token. For client-side tokens, commonly select read-only scopes like styles:read, geocode:forward, directions:read. For server-side tokens, you might add write scopes such as uploads:write or datasets:write. Granting fewer scopes is a critical security practice.
6. Set Restrictions (for Public Tokens): For public tokens, set URL restrictions (for web applications) or package bundle ID restrictions (for mobile applications) to limit where the token can be used. This adds an extra layer of security by ensuring the token only works from your specified domains or apps.
7. Generate Token: Click "Create token" to generate your new access token.
8. Copy Token: Immediately copy the generated token. Mapbox only displays the full secret token once upon creation. If you lose it, you will need to generate a new one.

Mapbox recommends using multiple tokens for different applications or environments (development, staging, production) to isolate access and simplify revocation if a token is compromised.

Authenticated request example

The method for including the access token depends on whether you are using a Mapbox SDK or making direct HTTP requests. Here are examples for both:

Mapbox GL JS (Web SDK)

When using Mapbox GL JS, you set the access token when initializing the map:

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v11',
  center: [-74.5, 40],
  zoom: 9
});

Replace 'YOUR_MAPBOX_ACCESS_TOKEN' with your actual public access token.

Direct API Request (Geocoding API example)

For direct HTTP requests, the access token is typically passed as a query parameter:

curl "https://api.mapbox.com/geocoding/v5/mapbox.places/Los%20Angeles.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Ensure you replace YOUR_MAPBOX_ACCESS_TOKEN with your valid Mapbox access token. For server-side applications, it is a recommended practice to store this token securely, for instance, via environment variables, rather than hardcoding it.

Security best practices

Securing your Mapbox access tokens is crucial to prevent unauthorized use and manage your account's usage limits. Follow these best practices:

• Restrict Token Scopes: Always assign the minimum necessary scopes to each token. A token used only for displaying maps doesn't need write permissions for datasets.
• Use URL Restrictions (for Public Tokens): For client-side tokens, set URL restrictions to allow API requests only from specific domains. This prevents others from using your token if it's extracted from your client-side code. For mobile apps, use bundle ID restrictions.
• Never Expose Secret Tokens: Secret access tokens should only be used on your server-side applications. Never embed them in client-side code (HTML, JavaScript, mobile app bundles).
• Store Secret Tokens Securely: When using secret tokens, store them in environment variables, a secrets management service (e.g., AWS Secrets Manager, Google Secret Manager), or a secure configuration file that is not committed to version control. Avoid hardcoding tokens directly in your source code.
• Rotate Tokens Regularly: Periodically generate new tokens and deprecate old ones. This minimizes the window of opportunity for a compromised token to be exploited.
• Monitor Token Usage: Regularly review your Mapbox dashboard for unusual API usage patterns that might indicate a compromised token.
• Use Separate Tokens for Different Environments/Applications: Create distinct tokens for development, staging, and production environments, and for different applications. This limits the impact if one token is compromised and simplifies revocation.
• Revoke Compromised Tokens Immediately: If you suspect a token has been compromised, revoke it immediately from your Mapbox Account Dashboard.
• Educate Your Team: Ensure all developers working with Mapbox understand token security best practices.