Sites

A site is a registered domain plus the API key that authorizes the BreakGround SDK to run on it. Each site is a tenancy boundary for analytics, audiences, and content — sessions captured under one site stay isolated from another. Manage your sites from Settings > Sites.

Site Limits

Most plans cap the number of active sites. The Sites page shows your current usage (e.g. 2 of 5 used) at the top. If you've hit the limit, delete an unused site or upgrade your plan before adding another.

Creating a Site

1. Click Add Site.
2. Enter a Site Name (up to 20 characters, used internally to identify the site).
3. Enter the Domain (up to 253 characters, e.g. app.example.com). Domains are normalized to lowercase.
4. Optionally enable Allow Subdomains to authorize traffic from any subdomain of the parent domain (*.example.com).
5. Click Create. The site is created and a new API key is issued immediately.

After creation, the AI Mapping modal opens automatically so the platform can crawl the site and prepare it for content authoring. See AI Mapping below.

API Keys

Every site has exactly one active API key, hashed at rest. The full key is shown to you in three situations only:

• Once, in the green banner that appears immediately after the site is created.
• Once, in the amber banner that appears immediately after you regenerate the key.
• Inline in the SDK Snippet copy block on the site card.

note

Save the key the first time you see it. After the banner disappears, only the prefix (e.g. bg_live_abc1...) is visible until you regenerate. Regenerating invalidates the previous key.

Regenerating a Key

If a key is leaked or you're rotating credentials:

1. Open the site card and click Regenerate API Key.
2. Confirm in the dialog.
3. Copy the new key from the amber banner that appears.
4. Update your SDK installation with the new key. The previous key stops working immediately.

Regenerating requires the MANAGER role or higher.

SDK Snippet

Each site card has a View Snippet action that expands to show the <script> tag with the API key inlined. Copy this snippet into your application's HTML to install the SDK on that domain. See SDK Installation for framework-specific guides.

AI Mapping

When a site is created, BreakGround attempts to crawl your domain and build a map of pages, selectors, and routes. This map powers content authoring and targeting. The status badge on each site card reflects the current state:

Status	Meaning
AI Mapping	Crawl is in progress. Content authoring is limited until it completes.
AI Enabled	Crawl succeeded. Full AI-assisted authoring is available for this site.
Failed	Crawl could not complete. Click Retry to try again (up to 3 attempts).
(no badge)	Mapping has not been started. Click Enable AI to begin.

Enabling or Retrying Mapping

Clicking Enable AI (or Retry on a failed mapping) opens the Enable AI creation dialog. Provide demo-account credentials so the crawler can sign in and walk the authenticated parts of your application:

Field	What to enter
Login URL	The sign-in page on your site (e.g. https://app.example.com/login). Must be on the same domain as the site.
Demo username / email	The username or email of a dedicated demo account.
Demo password	The password for the demo account. Stored encrypted at rest and used only for mapping.

caution

Use a dedicated demo account, not real customer or admin credentials. Treat the account as you would any service credential and give it the minimum access needed to render representative pages.

Click Verify & start mapping. BreakGround loads the Login URL in a headless browser and confirms the credentials work before queuing the mapping job. If verification fails, the dialog displays a specific message — bad credentials, no login form found, page didn't load, or timeout — so you can correct the issue and retry.

Once verification succeeds, the mapping job runs in the background. You'll receive an email when it's done; you can close the dialog and keep working in the meantime.

When Mapping Fails

If mapping fails repeatedly, check that:

• The domain is publicly reachable from the open internet (not VPN-only or IP-allowlisted).
• The Login URL renders an actual sign-in form, not a redirect chain or SSO bounce.
• The demo account is unlocked, unexpired, and exempt from MFA challenges (the crawler can't complete a TOTP or magic-link flow).
• The account has access to enough representative pages for the map to be useful.

After three failed attempts, the Retry action is disabled and you'll need to contact support to investigate further.

Editing a Site

Click Edit on a site card to update its name, domain, or subdomain setting inline. Changing the domain does not issue a new API key — the existing key continues to work, but the site will only authorize requests from the new domain.

Deleting a Site

Deleting a site permanently removes its API key, mapping data, and association with all content targeting that site. Sessions and analytics already captured remain in your historical data but are no longer attributed to an active site.

1. Open the site card and click Delete.
2. Confirm in the dialog.

Deletion requires the MANAGER role or higher and cannot be undone.