Verify a browser origin

When you create an application in admin, you list allowed browser origins — the hostnames where your app loads the StringPush SDK in the browser (for example app.example.com or localhost:5173).

Each origin you add is saved immediately, but it is not active until you prove you control it. Until verification succeeds:

• Browser requests from that origin get CORS errors (the API will not return Access-Control-Allow-Origin).
• Runtime API key auth rejects the Origin header (manifest and overlay return 403).

One allowlist in admin controls both checks — you do not configure CORS separately.

---

When you create an application

This is the flow in Projects → New application (or when editing an existing application):

1. Enter a name for the application (for example Web app or Marketing site).

2. List browser origins under Allowed browser origins — one hostname per line or comma-separated:

   • Your staging site: staging.example.com
   • Your production site (add now or later): app.example.com
   • Local dev: localhost:5173 (or the port your dev server uses)

   Do not include https:// — hostnames only.

3. Create application (or Save application when editing).
   Copy the Application ID and runtime API key when shown — the key is displayed once.

4. Check verification status — below the origins field you will see a row for each hostname:

   • Dev origin — localhost entries are active immediately (no DNS step).
   • Verify required — you must complete verification before browser SDK calls work from this hostname.

5. Verify each non-localhost origin:

   • Click Verify next to the hostname.
   • Add the DNS TXT record (recommended) or publish the HTTP file (fallback).
   • Wait a few minutes for DNS propagation, then click Check verification.
   • Status changes to Verified — browser requests from that origin are now allowed.

6. Publish staging bundles in Keys, then load the SDK from a verified origin (your staging site, local dev, or a local sample app on localhost).

Quick local try

Add localhost:5173 (or localhost:5177 if you run the sample app locally). Localhost origins skip DNS verification so you can wire init() and see strings in minutes.

Platform hostnames

You cannot add StringPush platform domains (for example *.stringpush.com, admin, ops, or the hosted sample hostname) to your application. Use your staging or production hostname, or localhost for development.

---

Verification methods

DNS TXT (recommended)

After you click Verify, admin shows:

Field	Example
DNS TXT — name	_stringpush.app.example.com
DNS TXT — value	stringpush-verify=sp_…

Add a TXT record at your DNS provider with exactly those values. Propagation can take a few minutes (sometimes up to an hour).

Common providers

Provider	Where to add it
Cloudflare	DNS → Records → Add TXT
AWS Route 53	Hosted zone → Create record → TXT
Google Cloud DNS	Zone → Add record set → TXT

Then return to admin and click Check verification.

HTTP fallback

If you cannot edit DNS (some preview hosts), publish a plain-text file on your site:

Item	Value
URL	https://<your-host>/.well-known/stringpush-verification
Body	The exact token string from admin (starts with stringpush-verify=)

The file must be served over HTTPS with Content-Type: text/plain (or empty) and return 200 without redirects to another host.

Use Check verification in admin after the file is live.

---

Wildcard origins

You may add wildcard hostnames such as *.staging.example.com.

• Verify the parent hostname first (for example staging.example.com).
• Wildcard rows stay inactive until the parent is Verified.

---

Status reference

Badge in admin	Meaning
Verify required	Saved but inactive — complete DNS or HTTP verification
Verified	Active for runtime key auth and browser CORS
Verification failed	Last check did not find the record — fix DNS/HTTP and check again
Re-verify required	Previous verification expired — repeat the DNS or HTTP step with a new token
Dev origin	Localhost — active without verification (development only)

---

Troubleshooting

Symptom	What to check
Browser CORS error on manifest or overlay	Origin not Verified yet — open admin → Projects → application → Verify → Check verification
403 / “Origin not allowed” with a valid runtime key	Same as above; confirm init({ origin }) matches the verified hostname (including port for localhost)
Verification failed after DNS change	TXT name must be _stringpush.<host> (not @ unless verifying the apex); value must match exactly; wait for TTL
HTTP check failed	File must be at /.well-known/stringpush-verification, HTTPS, no auth wall, body matches token
Works on localhost but not staging	Staging hostname is still Verify required — complete verification for that row
Cannot add a hostname	Platform/reserved domains (*.stringpush.com, admin, API) are blocked; use your own domain or localhost
Wildcard still inactive	Verify the parent domain first

---

Production origins

Add production hostnames (for example app.example.com) to the same application before you ship. Each new hostname goes through the same Verify required → Verified flow.

When you call init({ environment: "production" }), the runtime key and origin checks use the same verified allowlist.

---

Next

• Getting started — full first-string walkthrough
• Integration hub — React, Vue, Angular, Next.js
• Sample app — try the SDK locally or on the hosted demo
• Staging overlay — in-context editing