Environments

note

The URLs and credentials on this page are partner-facing facts your CoinTracker integration owner will confirm during kickoff. If anything here doesn't match what they sent you, trust the credentials they sent.

The kit runs against three environments. You select between them with two independent props on TaxKitProvider:

• options.mode — selects the backend behavior the iframe uses (production data, alpha data, or stubbed mocks).
• options.apiBaseUrl — selects the origin the iframe is loaded from. Defaults to https://embedded.cointracker.com regardless of mode.

You usually set both together when you want to point at staging.

The three environments

Environment	options.mode	options.apiBaseUrl	Typical use
Production	'production' (or omit)	'https://embedded.cointracker.com' (default)	Your shipped build.
Staging	'alpha'	'https://embedded-staging.cointracker.com'	Pre-launch integration testing; matches CT staging.
Mock (local)	'mock'	Default (or whatever apiBaseUrl serves the mock GraphQL endpoint)	Local UI iteration, demos.

'production' is the default mode — if you omit options.mode, you get production behavior. Setting mode: 'alpha' does NOT change the iframe origin on its own — you must also set options.apiBaseUrl to the staging origin if you want the staging iframe.

Per-environment credentials

CoinTracker delivers a separate set of credentials per environment during kickoff. Don't share them across envs — staging credentials minting a production JWT (or vice versa) will fail signature validation.

What you'll receive per env:

• Auth0 Application Client ID — used by CoinTracker's iframe to validate your minted JWTs.
• Allowed parent origins — every domain where you'll embed the iframe in that env. Registered server-side at CoinTracker. No wildcards. Missing origins → silent CORS failure.
• Webhook signing secret (HMAC) or bearer-audience (bearer) — used to authenticate webhook deliveries to your receiver. See Webhooks.
• Staging iframe URL — only for non-prod envs.

Switching environments

Set options.mode and options.apiBaseUrl together based on your own deploy environment:

const ENV = import.meta.env.MODE; // your build's env

<TaxKitProvider
  fetchAccessToken={fetchAccessToken}
  options={
    ENV === 'production'
      ? { mode: 'production' } // apiBaseUrl defaults to embedded.cointracker.com
      : ENV === 'staging'
        ? {
            mode: 'alpha',
            apiBaseUrl: 'https://embedded-staging.cointracker.com',
          }
        : { mode: 'mock' } // local dev — apiBaseUrl irrelevant
  }
>
  <YourApp />
</TaxKitProvider>;

Your token-minter must mint JWTs signed against the matching environment's signing key, and your webhook receiver must use the matching environment's HMAC secret. The simplest pattern is one set of partner-side env vars per CoinTracker environment, driven by your own deploy pipeline.

Origin allowlists

CoinTracker maintains an explicit per-environment allowlist of parent origins permitted to embed the iframe. Adding a new origin (a new partner subdomain, a new preview-deploy domain, etc.) requires sending CoinTracker the exact origin string and waiting for them to deploy the updated allowlist. There are no wildcards.

The practical implication: if you have many short-lived preview URLs (e.g. one per pull request on a service like Vercel), embed the kit against a stable subdomain in those envs rather than expecting CT to allowlist every preview URL. Or use options.mode: 'mock' for preview-only flows so you don't need a CT-served origin at all.

What happens when an environment is misconfigured

Symptoms and what to check:

Symptom	Likely cause
Iframe loads but every GraphQL call 401s	JWT signed for wrong env (staging key against prod backend, or vice versa)
Iframe doesn't load — CORS error in console	Your parent origin isn't in the env's allowlist
Webhook deliveries fail signature verification	Using the wrong env's HMAC secret on your receiver
TaxKitError.EmbeddedHealthCheckError on load	iframe origin unreachable — likely a CT outage; check status.cointracker.io

See Troubleshooting for full debugging patterns.