Mapbox Access Token

In order to use the Mapbox API, you will need an Access Token. Follow these authoritative instructions for getting a Mapbox Access Token...

# Creating an Access Token

Mapbox Web Services APIs

The Mapbox API actually consists of a collection of multiple Web Services APIs (opens new window).

# Token Scopes

When creating a new token, you can usually leave the default configuration unchanged. By default, the token will have all the necessary permissions to operate on your site.

Screenshot of the Token Scopes option in the Mapbox interface

# Token Restrictions

If desired, you can optionally restrict the token to only work on specified domains or subdomains...

Screenshot of the Token Restrictions options in the Mapbox interface

# Adding your token to Craft

Once you have created an Access Token, you will need to add it to your Craft site. There are a few different ways to approach this, so go with what works for your setup. The preferred method is to set your token in the project's .env file.

You can find the Access Token field on the Settings > Mapbox page in your control panel:

Screenshot of a Mapbox Access Token field

# Setting token in the field directly

Discouraged - Don't do this

Storing your Access Token directly in the Settings field is discouraged. It is considered a minor security risk, because your unsecured token will end up in the database, as well as in the project config files (and therefore your Git repo).

This is the least preferred method of storing your token. Saving it directly in the Settings field is the least secure solution, and prevents you from using different tokens in different environments.

We do not recommend storing your Access Token directly in the Settings field.

# Setting token in .env

Encouraged - Do this

Using an .env file is the most secure and most flexible way to store your Access Token.

This is the preferred approach. Presumptively, you already have your database and other system details stored in an .env file. Simply add your Access Token to that file, and the settings page will automatically be able to recognize it.

# Mapbox Access Token

Once that's in place in your .env file, it will be possible for the settings page to recognize that value:

Screenshot of a Mapbox Access Token field with value from the .env file

Craft will store a reference to the token, instead of storing the token itself. This allows you to keep your unsecured token out of the database, and out of the project config files. It also gives you the flexibility to use different tokens in different environments.

# Setting token in a PHP config file

Lastly, it's possible to store the Access Token in a PHP config file. While this is a solid approach, it doesn't offer many inherent advantages over simply setting your token in the .env file.

For more information, read about the PHP Config File...