Collaboration best practices

Join the Mapbox Developers Discord Communityarrow-right

This guide outlines best practices for setting up an account so that necessary stakeholders can access it. We also highlight recommendations for multiple collaborators working together on a project.

If you are locked out of an account and need to regain access, see the guide for regaining access to your account or contact support.

Best practices for setting up an account

Mapbox accounts are shared accounts. Mapbox accounts do not support individual user accounts, or a nested account hierarchy in which multiple accounts are connected to one another. When sharing an account, we recommend you manage your organization's access to Mapbox accounts 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, while adding another level of security.

There are a few guidelines you can follow to set your account up well for collaboration from the beginning.

Setting up an account for a team

• Account setup. Once an account is created, the account ID cannot be changed, so consider using an ID like Company-Project or Project-Production that will be suitable for multiple collaborators. Note that the email address registered to the account receives all important notifications for the account and is considered to be the account owner. We recommend registering the account with an address that multiple members of your organization have access to, like project-team@company.com or engineering@company.com, so important account notifications are available to all stakeholders. Immediately store these credentials in a shared-secure location, like a 1Password vault and/or Okta. This will help keep your password safe and available when you or your teammates need it. Even if your account has SAML SSO enabled, there will be a password associated with the account. Save this password in a secure location with limited access.

• Authentication management. If your organization uses an identity provider (IdP) like Okta that supports the SAML2.0 protocol, consider enabling SAML Single-sign on. By using the organization's IdP for authentication to Mapbox from the beginning, you will not need to worry about sharing a password to an account or needing to change the password when a teammate departs. You'll also be able to assign user roles with specific permissions with SSO. Further, your organization's IT department can help troubleshoot if you are locked out of the account or need to provision access to a new teammate or collaborator.

• Access token management. Generally we recommend using distinct access tokens for each of your applications. By using a distinct token for each application, API and SDK usage can be monitored on a per app basis with the Statistics page. Using designated tokens for development, staging, QA, and production is also recommended for granular Statistics tracking. If you're working with developers that do not need full access to the account, consider creating a token for them with the minimum scopes their work requires, and including an identifier like their name, initials, or project in the token's name for usage tracking. Tokens can be created and deleted with the Access Tokens page or the Tokens API on the command line. With scoped tokens, developers can read, write, and upload data without needing to log into your Mapbox account.

• Notification management. Accounts only support a single registered email address. Consider registering the account with an address multiple stakeholders have access to, or, setting forwarding rules in your email client so those stakeholders in your company are forwarded important emails when the registered address receives them. For example, if you'd like your billing department to receive billing emails like payment receipts, set any email from billing@mapbox.com to automatically forward to them.

Setting up an account for a client

• Account setup. When using Mapbox in a project that might have another long-term owner, start by setting up a new account in the organization’s name, like CompanyName or Company-Project. This is an important step because account IDs cannot be changed and access tokens are non-transferable between accounts, so if someone else might need to take over managing this account, it should be setup for this from the beginning.

• Account management. If you are building projects for multiple clients, it might be best to set up unique Mapbox accounts for each of them. This 1:1 setup enables your client to assume ownership of their account in the future, access usage statistics for their projects, pay the invoices directly, and receive the free tier of API calls each month for no charge.

• Authentication methods. If your client uses an identity provider (IdP) like Okta that supports the SAML2.0 protocol, consider enabling SAML Single-sign on. By using the organization's IdP for authentication to Mapbox from the beginning, you will not need to worry about transferring ownership of the account over to the client in the future. Additionally, user roles with specific permissions for each role can be used with SSO. Further, passwords will not need to be shared for the account.

• Notification management. Accounts only support a single registered email address. Consider setting forwarding rules in your email client so that your clients and stakeholders receive important emails. For example, if you'd like your client to receive billing emails like payment receipts, set any email from billing@mapbox.com to automatically forward to them.

• Access token management. If you are managing multiple clients' projects from one Mapbox account, use a unique named token for each project. Be cautious about using your own account's access tokens while developing for an organization, since their resources & billing will be tied to your account. When the time comes to hand off the account, rotate tokens so that your client's maps are tied to their own access tokens. Take extra care not to delete an access token that is in production for a project you collaborated on before.

• Ownership management. When it's time to transition the client into the account owner role, you might need to share the account credentials with the organization so the owners can change the email and change the password to assume full ownership of the account. Encourage the organization to use an email address multiple people have access to and to save their new password in a shared password manager, like 1Password. Contact support with questions about transferring ownership of an account or regaining access to an account.

Inheriting an account from a developer, designer, or consultant

If someone else has created the Mapbox account that your application is using and is handing it off to you, we recommend the steps below for a thorough, proactive change of ownership.

• Account credentials. When changing ownership of the account to yourself or current organization, encourage the outgoing owner to change the registered email address to a valid, shared email like engineering@yourcompany.com. This will allow stakeholders to log in to the account to change the password as well as receive invoices, notifications, and password reset emails.

• Authentication methods. As your team is inheriting the account, consider enabling SAML Single-sign on as the primary authentication method if your organization uses an identity provider that supports the SAML2.0 protocol. With SSO, your users can also be assigned user roles with specific permissions for each role. With SSO enabled, your team will not need to share a password for the account.

• Password management. When you receive and/or create your Mapbox account credentials, store them in a shared-secure location, like a 1Password vault and/or Okta. This will help keep your password safe and available when you or your teammates need it. Even if your account has SAML SSO enabled, there will be a password associated with the account. Save this password in a secure location with limited access.

• Access token management. Taking care to rotate your access tokens upon receiving the account allows you to limit the risk of a consulting developer or former teammate deleting an access token that is used by a production application. Make sure that the location services for your applications are tied to your account, using distinct access tokens for granular statistics & billing.

Best practices for collaborating on projects

• Authentication methods. If your organization uses an identity provider (IdP) like Okta that supports the SAML2.0 protocol, consider enabling SAML Single-sign on. By using the organization's IdP for authentication to Mapbox from the beginning, you will not need to worry about sharing a password to an account or needing to change the password when a teammate departs. You'll also be able to assign user roles with specific permissions with SSO. Further, your organization's IT department can help troubleshoot if you are locked out of the account or need to provision access to a new teammate or collaborator.

• Access token management. Tokens can be created and deleted with the access tokens page or the Tokens API on the command line. With scoped tokens, developers can read, write, and upload data without needing to log into your Mapbox account. If your organization already has an existing Mapbox account and/or you hire developers (independently, or through our Developer Network), consider administering the developers access tokens with limited scopes. Access tokens cannot be transferred between accounts. Access token deletions are final.

• Resource management. Styles can be transferred between accounts, but Tilesets cannot be exported from one account and transferred to another. There is no programmatic way to move resources from one account to another - contact us with questions.

• Sharing resources for review. Throughout the project you can share your work with your Map Style's Share URL or by setting up a small example application with Mapbox GL JS. If collaboration on editing a style is required, but you don't share access to the same Mapbox account, follow the guide to transferring styles between accounts to share a style with a collaborator to work on in their own account.

Still have questions? Explore our Account documentation or send us a note. We're here to help.

Join the Mapbox Developers Discord Communityarrow-right

Was this page helpful?