Connectors

Connectors sync data from the tools your ventures already run on — payment processors, banks, cloud providers, ad platforms, AI APIs — so revenue and costs flow into Kordox automatically and become real, per-venture profit.

Everything a connector pulls is read-only. Kordox never moves money, changes settings, or writes anything back to the connected account.

How connectors work

The flow is the same for every provider:

1. Add — open a venture → Connectors tab (or Finance → Data sources), click Connect source, and pick a provider.
2. Authorize — either one-click OAuth (you approve read access on the provider's own screen) or paste an API key / token you create in the provider's dashboard. The panel shows the exact steps and links straight to the right page.
3. Verify — Kordox checks the credential immediately and tells you if a scope or permission is missing.
4. Initial sync — the first pull runs automatically and backfills recent history.
5. Stay fresh — Kordox re-syncs on a schedule (every ~6 hours); you can also Sync manually anytime.
6. Attribute — synced transactions are routed to the venture they belong to (see Attributing money to ventures).

Scoped to a venture

Connectors are scoped to a venture, so each venture only sees its own connected accounts and data. Infrastructure and AI costs can then be split across ventures by attribution.

Security — how credentials are handled

• Read-only by design. Every connector asks only for read scopes (billing, charges, orders, cost reports). Nothing Kordox holds can spend, refund, or reconfigure your account.
• Encrypted at rest. API keys and OAuth tokens are encrypted before storage and never returned to the browser after you save them.
• Least privilege. Where a provider supports scoped credentials (Stripe restricted keys, Cloudflare scoped tokens, AWS IAM policies), the guide asks for the narrowest permission that works — listed per connector below.
• Revoke anytime. Disconnecting removes Kordox's access and stops syncing. Data already synced stays in your ledger.

Available connectors

Category	Providers	Connect via
Revenue	Stripe, Shopify, PayPal, Square	OAuth (Stripe/Shopify) or API key
Cash / bank	Plaid (balances feed runway)	API key + Link token
Infrastructure cost	Cloudflare, AWS Billing, GCP Billing	API key or OAuth (GCP)
Ad spend	Meta Ads, Google Ads	OAuth
AI & tokens	Anthropic (Claude), OpenAI	Admin API key
Email	Forward/BCC + reply from a record	Not a connector — see Email

Sync, status & freshness

• Schedule. Kordox re-syncs active connectors automatically every ~6 hours.
• Manual sync. Trigger a refresh anytime from a connector's row (or Sync all for a category). Manual sync just runs the same pull sooner.
• Status. Each connector shows its last-synced time, the amount and transaction count over the last 30 days, and the attributed percentage.
• Needs attention. A failing connector surfaces at the top with the exact error and a Verify / Sync / Configure shortcut. Transient upstream errors retry automatically and self-heal on the next scheduled sync.
• History. The History button shows recent sync runs and their results.

What each connector needs

Stripe — payments

Syncs payments, payouts, refunds and fees into per-venture P&L. Read-only.

• Permissions: a restricted API key with read on Balance, Charges, Refunds, Subscriptions. (Add write on Checkout Sessions only if you turn on client invoicing — it's off by default and not needed for sync.)
• Steps: Stripe → Developers → API keys → create a restricted key with the scopes above → paste it → Add account. Money settles in your Stripe; the key can't move it.

Shopify — orders

Syncs your store's orders and refunds as revenue. Read-only.

• Permissions (OAuth): read_orders, read_products.
• Steps: enter your mystore.myshopify.com domain → Connect via Shopify → approve read access → you're redirected back and orders sync as revenue.
• You'll need: a staff account allowed to install apps.

PayPal — payments

Syncs PayPal transactions as revenue.

• Permissions: a PayPal REST app — its Client ID + Secret (Transaction Search is read-only).
• Steps: developer.paypal.com → Apps & Credentials → open/create a REST app → copy Client ID + Secret → paste both → pick Live (or Sandbox) → save.

Square — payments

Syncs Square payments and refunds as revenue.

• Permissions: a Square access token (PAYMENTS_READ).
• Steps: developer.squareup.com → your app → Credentials → copy the access token → paste it, optionally add a Location ID to limit to one location → pick the environment → save.

Plaid — bank balances

Connects bank balances so runway is based on real cash.

• Permissions: Plaid Client ID + Secret and an item access token from Plaid Link (Balance product).
• Steps: copy Client ID + Secret from the Plaid dashboard → use Plaid Link to connect the bank and get an access token → paste all three → pick the environment (production/sandbox) → save.

Cloudflare — infrastructure cost

Tracks Cloudflare usage and billing costs.

• Permissions: a custom API token with a single permission — Account → Billing → Read, scoped to your account.
• Steps: Dashboard → My Profile → API Tokens → Create Token (Billing Read) → copy it → paste it, plus your Account ID (right sidebar of any domain's Overview) → save. Kordox verifies immediately.

AWS Billing — infrastructure cost

Pulls AWS cost & usage into the right venture's P&L.

• Permissions: an IAM user/key allowed to call ce:GetCostAndUsage (AWS Cost Explorer). The managed AWSBillingReadOnlyAccess policy covers it.
• Steps: IAM → attach the policy to a user → create an access key → paste the access key ID + secret → optionally set a region (defaults to us-east-1) → save.

GCP Billing — infrastructure cost

Pulls Google Cloud spend so infrastructure costs land in the right venture's P&L — per GCP project, per service, per day.

• Connect (one click): choose Connect with your Google account and sign in with the identity that owns your GCP. Kordox auto-detects your billing account and BigQuery billing export — most setups need zero typing.
• Permissions (OAuth): cloud-billing.readonly + bigquery.readonly.
• The one manual GCP step: cost data comes from Cloud Billing's BigQuery export, which can only be enabled in the console — Billing → Billing export → Standard usage cost → pick a project + dataset. If it isn't on yet, the connector's checklist deep-links you there. First data lands ~24h after enabling (no historical backfill).
• Advanced (no OAuth): paste a service-account JSON key with Billing Account Viewer + BigQuery read instead — useful for machine accounts.
• Changed something in GCP? Use Re-detect from Google on the card to re-run auto-detection and pick the right billing account.

Meta Ads — ad spend

Imports Meta (Facebook/Instagram) ad spend as a cost so margins and CAC are real.

• Permissions (OAuth): ads_read.
• Steps: Connect via OAuth → approve read access → choose the ad account to sync → spend imports as expenses.

Google Ads — ad spend

Imports Google Ads spend as a cost for true margin and CAC.

• Permissions (OAuth): read access to your Google Ads data; you'll confirm the customer ID.
• Steps: Connect via OAuth → approve read access → select the account / confirm the customer ID → spend imports as expenses.

Anthropic (Claude) — AI & tokens

Tracks your Claude API and workspace spend as AI costs, per workspace — so each venture's AI bill is real.

• Permissions: an organization admin role and an Admin API key (sk-ant-admin…). A regular API key cannot read org usage. Kordox reads only the daily cost report.
• Steps: console.anthropic.com → Settings → Admin keys (not the regular API-keys page) → create an Admin key → paste it here.
• Attribution: each Claude workspace maps to a venture, exactly like GCP projects.

OpenAI — AI & tokens

Tracks your OpenAI API spend as AI costs, per project.

• Permissions: an organization owner/admin role and an Admin API key (sk-admin…). Kordox reads only daily costs.
• Steps: platform.openai.com → Settings → Organization → Admin keys → create an admin key → paste it here.
• Attribution: each OpenAI project maps to a venture.

Attributing money to ventures

Kordox routes every synced transaction to the venture it belongs to, so per-venture P&L is real instead of "whatever account it came from." Both mechanisms are retroactive — Kordox re-attributes existing history when you save and re-sync.

Source mapping — for providers with clean sub-entities. GCP costs map by cloud project, Cloudflare by account, Claude/OpenAI by workspace/project. Edit in Finance → Cloud costs → Attribution.

Attribution rules — for providers without clean sub-entities (Stripe descriptors, bank memos). A rule says "description contains X → venture Y": any transaction whose description contains that text (case-insensitive) lands on that venture; first matching rule wins. Edit in Finance → Money explorer → Attribution rules, then Save & re-sync.

Money explorer

Finance → Money explorer slices all synced money — revenue, infrastructure, ads, AI, fees — by category, provider, source, service, venture, or type, over any period. Toggle between Money in, Money out, and Net, and export the current view as an Excel workbook, a branded PDF report, or CSV.

Troubleshooting

• "Needs attention" with a sync error. Open the error text — it now includes the upstream HTTP status. 401/403 means the key/token lacks a required scope (re-create it with the permissions listed above). Transient 5xx/rate-limit errors retry automatically and clear on the next scheduled sync.
• Connected but no data. Some providers lag: GCP's BigQuery export lands the first data ~24h after you enable it; AI cost reports lag ~1–2 days. Give it a cycle, then Sync.
• Costs on the wrong venture. Set up attribution and Save & re-sync — it re-attributes history, not just new data.
• Verify fails immediately. The credential is wrong or missing a scope; the panel names what's missing. Re-create the key and paste it again.