Integration planning

The kit is straightforward to wire up, but a few decisions and a few pieces of information need to be locked in before your kickoff with CoinTracker. This page is a checklist for the partner-side lead — the person organizing the integration on your end.

Most decisions have a sensible default. The ones that don't have defaults must be specified.

Decisions with defaults

Decision	Default	When to deviate
Partner slug	(you provide; lowercase, immutable)	Always required; cannot change after launch.
Theme	iframe's default light/dark tokens	Only if your brand requires custom CSS tokens. See Theming.
Font	Default stack	Only if your brand requires a specific font.
Plan tiers	Reuse existing CoinTracker plans	Only if you negotiated custom pricing — requires Stripe products on CT side.
OAuth-driven exchange import	Not required	Only if your exchange is also a CoinTracker integration that supports OAuth-based import.
Webhook auth	HMAC-SHA256	Bearer token if you have existing M2M auth infrastructure. See Webhooks.
PKCE handling (OAuth + bearer)	CoinTracker handles PKCE	Your backend handles the auth-code exchange.
Custom legal / disclaimer copy	iframe defaults	Typically customized for compliance — see the copy prop.

Required regardless

These have no defaults. You must specify each for CoinTracker to enable your integration.

• Allowed parent origins per environment — every domain where the iframe will load (dev, staging, prod). No wildcards. Missing origins cause silent CORS failure.
• Webhook receiver URLs per environment — all HTTPS. See Webhooks.
• JWT signing approach — algorithm plus public key or JWKS endpoint. CoinTracker validates against this. See Authentication → Signing.
• Stable partner_user_id strategy — the value that uniquely identifies a user across sessions in your system. Cannot be a value that changes over a user's lifetime (e.g. not an email address).
• Plan limits — transfer cap and transaction cap for the user tier.
• Help / support URL — surfaced as the help link inside the iframe header.
• 3–5 test user IDs — partner-side IDs CoinTracker can mint JWTs for during build and integration testing.
• Logo SVG — square, transparent background.

What CoinTracker sends back

After kickoff, CoinTracker delivers (per environment, where applicable):

• Confirmed partner slug enrolled in the iframe's Partner enum.
• Auth0 Application Client IDs — one per environment.
• @cointracker/tax-kit package version that includes your partner enum value.
• Allowed Callback URLs registered in CoinTracker's Auth0 (for OAuth integrations).
• Webhook signing secret (if HMAC) or bearer-audience (if bearer auth).
• Staging iframe URL: https://embedded-staging.cointracker.com/sdk/.

Treat all of these as secrets where applicable — the Auth0 client IDs and webhook signing secrets in particular should live in your secret manager, not in source control.

Suggested pre-kickoff prep

Before the kickoff meeting:

1. Draft your decision table. Fill out the table above with your chosen value for each row. CoinTracker will walk through it with you.
2. Identify your partner_user_id source. Pick the column in your users table that's stable and immutable. Common choice: the primary key.
3. Set up a project in your secret manager with placeholder rows for the credentials CoinTracker will return. You'll fill these in after kickoff.
4. Pick the engineer who owns the JWT minter and the engineer who owns the webhook receiver. They don't have to be the same person, but both need to be on the kickoff call.

What happens at kickoff

A 30–60 minute call covers:

• Your answers to the decision table.
• CoinTracker walks you through the JWT claim shape, webhook payload, and OAuth handshake (if applicable).
• Exchange of credentials (Auth0 client IDs, signing secret, staging URL).
• Agreement on the rollout timeline (see Production rollout).

After kickoff, you have everything you need to start the Quickstart.