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, Customers, Invoices. Kordox reads each charge's invoice and each subscription's customer, so the last two are required, not extra. (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 restricted key → choose "Providing this key to a third-party application" (name it Kordox) → set the permissions above to Read, leave the rest at None → paste the key → 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.