Settings and account access
The Settings page is where you can manage an account's profile information, billing and authentication methods, and apps connected to the Mapbox account. To access the Settings page, log into the account and navigate to account.mapbox.com/settings.
Note that for accounts using SAML Single-sign on authentication, only users with the
Root role assigned in their identity provider can access and update settings.
All users who login to an account with the account's password assume
Root user privileges by default, and can access and update the account's settings. Alternatively, if the account has enabled SAML Single sign-on authentication, there are two user roles that are available:
Admin, which are assigned to users in an identity provider (like Okta). For accounts with SSO enabled, only users with the
Root role will be able to access and update settings as described below. Learn more about user roles in the SAML SSO documentation.
To be sure that you can receive important notifications about your account, all accounts must verify the registered email address by clicking a link that we send immediately upon account creation. The verification process must be completed to gain full access to the Mapbox applications. Verification links are valid for 24 hours and can be re-requested when logged into your account. If an account's email address is updated, you will be prompted to verify the new address.
Having trouble verifying your account's email address? Visit the troubleshooting section for recommendations.
Each Mapbox account supports one registered email address. To update an account's email address, follow these steps:
- Log in and navigate to your Account settings page, and click the
- Enter the new email address and click Save changes.
An account's registered email address is the primary email address to which we send important account and billing notifications. If you are inheriting an account from a team member, consultant, or client, update the primary email address to be one that multiple members of your organization have access to, like
firstname.lastname@example.org. Similarly, if you are transferring an account to a team, consultant, or client, changing the registered email address on the account from your own to one they have access to make sure important notifications are not missed.
It is not possible to change an account's ID (username). Doing so would break links to maps tied to that account and could cause other unanticipated problems with implementations that depend on that account ID.
Instead, you can add or change the account's organization name or create a new account, transfer your map styles and update your web and mobile applications to reference the new account's tokens and styles. For more information about setting up an account for collaboration or preparing for an ownership transition, see our guide for collaboration.
Once this transition is complete, you can delete the original account without breaking any links to your maps.
If an organization name is added in the account's Settings, this value is automatically included in the header of the account's invoices. To add or change the organization name, follow these steps:
- Log in and navigate to your Account settings page, and click the
- Enter the new or updated organization name and click Save changes.
Questions about updating the profile information for an account? Please visit the troubleshooting section for recommendations and next steps to contact support.
- Log in and navigate to your Account settings.
- Enter your current password and new password in the appropriate fields.
- If you have two-factor authentication enabled, enter your two-factor authentication code.
- Click Save new password.
If you're having trouble logging in to an account, try resetting the account's password by providing the email address that's associated with the account. We'll send the registered email on file for that account an email with further instructions to reset the password.
The link that we send in the password reset email is only valid for 24 hours. If you receive an
Invalid token error message or have waited more than 24 hours, you'll need to request another password reset email.
Questions about changing or resetting an account's password? Not receiving the reset password email? Visit the troubleshooting section for recommendations and next steps to contact support.
Mapbox is critical infrastructure for our customers. We go to significant lengths to protect the security of your account, your data, and your users. Please visit our Security page for more information about how we process payments, store data, and conduct regular audits.
An account's Security Settings page is where you can enable and manage SAML Single sign-on and/or two-factor authentication for an account.
Manage your organization's access to Mapbox accounts while adding another level of security with SAML Single sign-on (SSO). SSO enables members of your organization to authenticate into a Mapbox.com account through any trusted, third-party identity provider that supports the SAML2.0 protocol.
- SAML2.0 protocol
- Identity provider (IdP) initiated login
- Shared accounts that multiple users can access
- User roles of
Does not support:
- OAuth, OpenID Connect, Kerberos, other protocols
- Service provider (SP) initiated login
- Identity provider (IdP) initiated single logout
- Nested sub-account hierarchy of separate, connected accounts
- Multiple identity providers
- Domain control or domain lockout
- SAML authentication for Atlas on-premises
SAML Single sign-on for Mapbox can be configured with any identity provider that supports the SAML 2.0 protocol. Integrate the Mapbox SAML applications offered by Okta, Azure AD, and OneLogin for streamlined setup and IdP specific documentation, or learn more about the general steps for setting up SSO with any identity provider below.
- Okta Integration Network (OIN): Mapbox Okta verified SAML app
- Tutorial: How to configure SAML 2.0 with Mapbox
Azure Active Directory
- Azure AD Application Gallery: Mapbox SAML app in the Marketplace
- Tutorial: Azure Active Directory SSO integration with Mapbox
- OneLogin App Store: A Mapbox SAML app is available. Login to your onelogin portal, navigate to the Administration panel, click "Browse app catalogue", and search for "Mapbox".
- Tutorial: Coming soon
If there is not a Mapbox SAML application available in your IdP, you can create a custom SAML app for Mapbox. The setup workflow and terminology used by each identity provider can be unique, but there are general themes:
- Login to the Mapbox account you want to set up with SSO authentication, navigate to the SSO setup page
- In your identity provider (IdP), create a new SAML application
- Copy and paste the required details in the Configure your identity provider section of the Mapbox SSO setup page into your IdP’s configuration workflow
- Add the user roles as a custom attribute in your IdP
- Copy and paste the required details from your identity provider in the Setup SAML single sign-on for Mapbox section of the SSO setup page
- Click Enable single sign-on to save your integration
- Assign users to your application in the IdP
- Assign roles to the users
- Test that the SAML authentication is working as expected
- Activate Mapbox SSO to terminate all sessions.
Once SSO is enabled and activated, see our recommendations for enforcing SSO.
Log into your identity provider with the required administrative privileges, then create a custom SAML2.0 application for Mapbox. See the following external links for IdP specific instructions:
In this new application, enter the following values from the Mapbox SSO setup page:
- Single sign-on URL, also could be referred to as the
Assertion Consumer Service (ACS) URL,
Application ACS URL,
Callback URL, or
Post-back URLin your IdP.
- Audience Restriction, also could be referred to as
SP Entity ID,
Application SAML Audiencein your IdP.
- The application username must be in email format
- The SHA256 encryption algorithm is required
Through SAML SSO you can assign users roles that provide certain permissions in the Mapbox Account and Studio apps that are also enforced by all Mapbox APIs. User roles are assigned in the identity provider and transferred to Mapbox in the SAML assertion. The available user roles are:
|Users with the ||IT Admins, Product Owners, CTOs|
|Users with the ||Developers, Designers, Project contributors|
Many identity providers use custom attributes and attribute statements for roles. Typically, roles can be assigned to individuals or groups. Consult the documentation for your specific IdP, such as the Okta documentation for Mapbox SAML apps for details.
To complete the initial connection between your identity provider and mapbox.com, enter the required information in the Mapbox account's SSO setup page:
- Identity Provider sign-on URL, also could be referred to as
SAML endpoint, or
SSO sign-in URLin your IdP
- Issuer ID, also could be referred to as
Issuer URLin your IdP
- X.509 Certificate, pasted as text into the field.
Be sure to include
— BEGIN CERTIFICATE — and
— END CERTIFICATE — when pasting your X.509 certificate into the Mapbox form. You may need to open the X.509 certificate in a text editor in order to copy the full body.
Click Enable single sign-on to submit the form. You will be prompted to re-authenticate.
Once you have saved the integration, return to your identity provider to assign the application to yourself and/or another member of the organization for testing. When assigned, try clicking the tile, "chiclet", or link for your Mapbox app to login from your identity provider's portal. If you receive an error when attempting to login with SAML, you can adjust the settings by clicking the
edit single sign on.
Questions about setting up SAML SSO? Please visit the troubleshooting section for recommendations and next steps to contact support.
Enabling SSO for an account does not invalidate password authentication. The account's password is still a valid authentication method to make sure your organization's transition period to SAML authentication is seamless, and that direct password access to the account is available in the case of your identity provider has a service outage. Note that any users logging in with the account's password (and optional 2FA) will assume the
Root user role.
To encourage your users transition from password based authentication to SAML login through your IdP, we recommend the following once the integration has been tested successfully:
- Assign yourself the
Rootuser role in your IdP so you will have access to settings
- Assign most others the
Adminuser role so they will not have access to settings
- Change the email for the account to an email address that the
Rootuser(s) can access
- Save the new password in a safe location with least-privilege access (identity provider, shared password manager, IT vault)
- If 2FA is enabled for the account, either turn it off or save the recovery codes with the new password
- Announce to your organization that SAML SSO will be the primary, enforced mechanism for Mapbox access as of a future date. Encourage all users to test that they can access Mapbox with SAML before that date.
- On the date of enforcement, toggle the
Activate single sign onbutton on the account's Security Settings page to immediately terminate all of the account's active sessions.
- Change the password for the account, making the previous password invalid. As with activating Mapbox SSO, when the account's password is changed, all active sessions will be terminated. We recommend taking these two steps at the same time to prevent confusion for your users.
Once SSO is activated and the password has been changed, these updates should effectively push all application users to authentication with Single sign-on, as they'll no longer have the password.
You have the option to delete your SAML SSO integration. This is something you would need to do only in a rare situation -- generally, only if your organization has setup Single sign-on with a test account. Some identity providers can only be associated with a single Mapbox account. If you or your IT team has associated an IdP with a test account, we recommend deleting that integration before beginning setup for the organization's main account.
Questions about validating, enforcing, or deleting a SAML SSO integration? Please visit the troubleshooting section for recommendations and next steps to contact support.
Two-factor authentication (2FA), also known as multi-factor authentication (MFA) or two-step authentication, provides an optional, but recommended, layer of security for Mapbox accounts. Once enabled, all users will be prompted to enter the account's password as well as a security code generated on registered mobile devices whenever they log in to the account.
When logged in to an account, you can enable two-factor authentication from the Security page. The Security page will include a barcode which you'll be prompted to scan with your mobile device, or a code that can by typed into password management services like 1Password.
For a Windows phone, use the Authenticator app.
Your mobile device will display a 6-digit code. Type this code into the field below the barcode to complete the process.
Please note that enabling 2FA for an account raises the likelihood that you or other users of the account may have trouble logging into the account in the future. Mapbox verifies ownership of an account by asking users to confirm the credit card number on file for that account. When 2FA is enabled on an account without a credit card, there is no way that the Support team can help users regain access to that account. Exercise care by storing 2FA recovery codes in a safe place and distributing them to new account owners when transferring ownership of an account. Consider enabling SAML SSO for team accounts or accounts with multiple users, since many SSO providers require 2FA for logging into the IdP.
After you've set up two-factor authentication on an account, you will be redirected to a page with a recovery code. A recovery code is a single-use code that lets you sign in without your two-factor device.
Write down this code and keep it in a safe place. Treat your recovery code like a password to your account. If you lose your mobile device, you will need this code to log in to your account.
If you have already set up two-factor authentication on your account and do not have a recovery code, but can access the account with your 2FA device, go to your Security page to generate and retrieve a new recovery code for the account. Immediately store this code is a safe place, like a 1Password vault for individuals or teams.
To use the recovery code to login to an account, you'll need the account's account ID (username) or email, and the account's password. Follow the steps below to use your recovery code:
- Navigate to the Sign in page.
- Enter the account ID (username) and password, then click Sign in.
- Click the Lost your mobile device? link below the Sign in button. A new field for the recovery code will appear.
- Enter your recovery code in the new field and click Sign in.
Using the account's recovery code will temporarily deactivate two-factor authentication. This gives you a chance to configure a new two-factor authentication device, enable SAML SSO authentication for teams, or decide not to reactivate 2FA for the account.
Questions about enabling MFA or accessing an account with a recovery code? Please visit the troubleshooting section for recommendations and next steps to contact support.
You can delete an account by logging into your account, scrolling to the bottom of the Account settings, and clicking the Delete account button:
Account deletion is a permanent action that cannot be undone. We will not be able to recover your account, and the same account ID (username) cannot be re-used to create another account.
After clicking the button to delete an account, there will be a modal that requires additional confirmation that you do intend to fully delete the account. When an account is deleted, the following are effective immediately:
- All styles, projects, and data associated with the account are no longer available.
- The account cannot be logged into
- Access tokens tied to that account will be immediately terminated, and map implementations using them will no longer be able to effectively access Mapbox services.
Mapbox will not automatically prorate for any unused services or subscriptions, please contact our team for help.
Are you having trouble updating account settings, enabling SAML SSO, or logging into your account? Start here for some common troubleshooting tips for regaining account access or updating account settings. If you still cannot access your account after reviewing this documentation, include the details listed below in a support request. Our support team is standing by to help.
I'm not receiving the email to verify my account's email address. What can I do?
First, check that the email address registered to your account is a valid email address that has been spelled correctly, and that both the email address and email domain are configured to receive vendor email.
Invalid email addresses. Emails cannot be delivered if the address contains a spelling error, the mailbox is full, the inbox does not exist, or one of many other reasons why an email address is unable to receive messages. If the address is invalid, follow the prompts on the email confirmation page to update spelling errors or change the account's registered email. This begins the verification process again with the new address.
Valid email addresses. If you confirm that the email address is spelled properly and that the emails are not in your Spam folder or Promotions tab, allow for up to 60 minutes of latency throughout your email system. It's possible that your IT team maintains a filter above your inbox that requires additional processing and is delaying the email's arrival. Consider opening an internal ticket letting your IT team know about the problem, recommending they run a global search for emails from
email@example.com with the subject "verify your email address".
If the email address has not received an email after 60 minutes and is configured for receiving vendor email, please contact our team so we troubleshoot with you based on the specific error codes being surfaced by your email provider.
I'm not receiving the password reset email. What can I try next?
First, check your spam folder to make sure our email hasn't been routed there. Not seeing it there, either? Sometimes password reset emails are undeliverable - maybe emails from Mapbox to your email address have bounced in the past or there have been other problems preventing the email from being delivered (especially for inactive email addresses).
If you are not receiving the password reset email, let us know by submitting the support form.
I am locked out of a Mapbox account and need to regain access. What steps can I try?
If you need to gain access to a Mapbox.com account, please read the account lockout troubleshooting guide which provides recommendations for common scenarios. Still have questions? Please submit a support request including these details to get in touch with our team.
I do not have my two-factor (2FA) authentication recovery code. What are my options?
If you do not have a 2FA recovery code for an account with 2FA enabled, the account must have a payment method on file in order for the Mapbox team to verify ownership of the account and remove two-factor authentication. Contact our support team to get started.
If an account does not have a credit card on your account, we will not be able to verify account ownership. In this case, the only next step will be to create a new Mapbox account and add access tokens from your new account into your map implementations.
I'm having trouble setting up and/or configuring SAML Single Sign-on (SSO). Can you help?
If you're having issues setting up SSO after following the steps in our documentation, submit a support request to get in touch with our team. As we troubleshoot with you and help you successfully set up SSO, the more information about error codes and screenshots from your identity provider that you can include with your support request, the better!
We're happy to help with your questions - please contact our support team with this form. In order to help our team provide the most prompt resolution, please include as much of the following information with your request:
For account access issues:
- Account ID (username)
- Account's registered email address
- Access token (if applicable)
For failed login issues (with supported browsers):
- Web browser(s) and versions
- Any enabled web browser extensions you're using
- Any enabled experimental flags (chrome://flags/) if using Google Chrome
- Computer operating system and versions
- Whether you have tested this issue while in incognito mode (if applicable)
- Whether you have tested this issue with no browser extensions (if applicable)
If you do not know your browser information, you can use a tool like mybrowser.fyi to find the correct details.
With the information you provide, we'll try to diagnose the issue and provide tips that help you produce the desired behavior. Thanks in advance for providing as much information as you can!