The Map Integration settings page allows you to configure which map provider is used within their portal. Because different organisations have different billing arrangements, compliance requirements, or existing API relationships, the platform supports both a managed default option and the ability to connect your own credentials from Google Maps or Mapbox.
This article covers the following topics:
2.1 Understanding the Map Integration Page
2.2 Page Layout and UI Elements
2.3 Connecting a Custom Map Provider
2.4 Switching Between Providers
2.4.1 What Happens to the Previously Active Provider
2.4.2 Attempting to Switch to a Provider That Is Not Connected
1. Pre-Requisites
The table below lists areas of the platform that are relevant to this feature. Reviewing these before you begin will help you avoid common setup issues.
| Area | Why It Matters |
| Portal creation | Map Integration is configured per portal. Your portal must already exist before you can access the Map Integration settings page. |
| Frontend portal (maps feature) | The map provider configured here determines how maps are rendered in the frontend portal. Map display in the frontend is handled separately — this settings page controls only the provider and credentials. |
| Google Maps JavaScript API | If you intend to connect your own Google Maps API Key, that key must already be created and have the required services enabled in your Google Cloud account before you attempt to save it here. |
| Mapbox account | If you intend to connect your own Mapbox Access Token, that token must already exist in your Mapbox account before you attempt to save it here. |
2. Map Integration Settings
2.1 Understanding the Map Integration Page
The Map Integration page gives you control over which map provider powers their portal. Only one provider can be active at a time, and the configuration applies only to the portal you are currently managing.
By default, every portal uses the Platform Default (Google Maps API), which is managed by the platform. If your organisation prefers to use its own API credentials, you can connect those credentials here and switch to them once they are validated.
2.1.1 Where to Find This Page
- Click on Settings on the top bar
- Then, click on Maps
2.2 Page Layout and UI Elements
The Map Integration page contains several interactive elements. The table below describes each one, what it does, and what you should know before using it.
| Element | Description |
| Google Maps API (Platform Default) |
Selected by default on all newly created portals. Uses the platform's own API key, and no configuration effort is needed from you. This option is always available and always selectable, regardless of the status of your custom credentials. Billing is charged at a platform-defined rate per API call. |
| Google Maps API Key |
Allows you to activate your own Google Maps API Key as the map provider. This button is disabled by default and only becomes selectable once your Google API Key has been successfully validated and its status shows as "Connected". |
| Mapbox API Token | Allows you to activate your own Mapbox Access Token as the map provider. Like Point 2, this button is disabled by default and only becomes selectable once your Mapbox token has been validated and shows as "Connected". |
2.3 Connecting a Custom Map Provider
The process for connecting a Google Maps API Key and a Mapbox Access Token follows the same flow.
- Locate the input field for the provider you want to connect
- Enter your credentials into the relevant field. Each field accepts a maximum of 100 characters.
- Ensure the other credential field also contains alphanumeric input so that the Save button becomes enabled.
- Click Save.
- The system will begin server-side validation. During this time, the connection status for the provider will change from Not Connected to Validating.
- Once validation is complete, the status will update to one of the following outcomes
| Status | What It Means | What To Do |
| Not Connected | No credentials have been saved for this provider, or a previous attempt was cleared. This is the default state. | Enter your credentials and click Save to begin validation. |
| Validating | The platform is actively testing your credentials. This is a temporary loading state. | Wait for the process to complete — no action is needed. |
| Connected | Your credentials are valid and all required services are enabled. The provider's radio button (Point 2 or Point 4) is now selectable. | You may now select this provider to make it active. |
| Invalid Key / Connection Failed | Validation was unsuccessful. The credentials could not be verified or a required service is not enabled. | Check your credentials and required service configuration in your Google or Mapbox account, then re-enter and save. |
2.4 Switching Between Providers
Once one or more custom providers have a status of "Connected", you can switch between them and the Platform Default at any time by selecting the radio button beside the options. The selected provider becomes immediately active. All map requests in your portal will now use that provider's credentials.
2.4.1 What Happens to the Previously Active Provider
Only one provider can be active at a time. When you select a new provider, the previously active provider is automatically deactivated. It is not disconnected or deleted — its credentials and status are retained — but it will no longer serve map requests until it is selected again.
2.4.2 Attempting to Switch to a Provider That Is Not Connected
If a custom provider's status is not "Connected", its radio button is disabled and cannot be clicked. Hovering over it will display the tooltip:
"Connect API key before selecting"
This prevents you from accidentally activating a provider whose credentials have not yet been verified.
2.5 Delete Pending Restriction
If your portal's status is set to Delete Pending, the Map Integration settings page enters a read-only state. Specifically:
- All input fields become read-only and cannot be edited.
- Provider switching is disabled, you cannot change the active map provider.
This restriction exists to prevent configuration changes to a portal that is scheduled for deletion. If you believe your portal's Delete Pending status has been applied in error, support@bakuun.com before attempting any further configuration.
3. Troubleshooting
| Issue | Likely Cause | Resolution |
| Save button remains disabled after entering credentials | Only one of the two input fields contains input. Both fields must have alphanumeric values for the Save button to enable. | Enter a value in both the Google Maps API Key field and the Mapbox Access Token field, then attempt to save again. |
| Status stays on "Validating" for an extended period | The platform may be experiencing a delay reaching the provider's API, or there is a transient network issue. | Wait a short time and refresh the page. If the status does not update, re-enter your credentials and try saving again. If the issue persists, contact support. |
| Status changes to "Invalid Key / Connection Failed" after saving | The credentials entered are incorrect, expired, or the associated account does not have the required services enabled. | Log in to your Google Cloud or Mapbox account and verify that the key or token is active and that all required APIs and services are enabled. Re-enter the credentials on this page and save again. |
| Switching providers causes maps to stop working in the frontend portal | The newly activated provider's credentials may have passed validation but lack permissions for the specific map services used by the frontend. | Switch back to the Platform Default to restore map functionality immediately, then review the permissions and service configuration of your custom credentials before attempting to switch again. |