Survey Coder Connect

Connect is the integration model for platforms (not individual developers) that want to embed Survey Coder into their own product. Talk2Data was the first Connect partner; the same surface is open to anyone running a multi-tenant SaaS where end-customers ask their app to “code these verbatims.”

If you’re a solo developer or agency building your own scripts, you don’t need Connect — use a scp_live_* API key and you’re done. Connect is for when your customers are the ones whose data flows through Survey Coder.

How Connect differs from API keys

	API key (scp_live_*)	Connect (OAuth)
Identity	One key per Survey Coder org	One client_id per platform; one authorization per end-customer
Auth header	x-api-key: scp_live_...	Authorization: Bearer scp_at_...
Who pays	The org that owns the key	The Connect partner master org (post-pay invoice)
Audit trail	api_keys.last_used_at	connect_audit_log rows per action
Revocation	Partner can rotate their key	End-customer can revoke from /settings/connected-apps; partner can revoke from /v2/connect/authorizations
Multi-tenant	No — one org per key	Yes — one platform → many end-customer orgs

The two flows

Connect supports both Stripe-Connect-style flows depending on whether the end-customer already has a Survey Coder account.

Standard (linked) — when the end-customer is an existing SC customer

End-customer (in your app) → "Connect my Survey Coder account"
       ↓
Redirected to https://surveycoder.io/oauth/authorize?client_id=...&scope=...&state=...
       ↓
End-customer sees consent screen, clicks "Authorize"
       ↓
Redirected back to your redirect_uri with ?code=...&state=...
       ↓
Your backend exchanges the code at POST /oauth/token for access_token + refresh_token
       ↓
Every subsequent call uses `Authorization: Bearer <access_token>`
       ↓
Survey Coder scopes the request to the end-customer's org via RLS

The access_token is bound to that end-customer’s org_id. You cannot use it to operate on a different customer’s data.

Express (managed) — when the end-customer has no SC account

Your backend → POST /oauth/token grant_type=client_credentials
       ↓
Get an access_token tied to your partner master (no end-customer involvement)
       ↓
POST /v2/connect/managed-orgs { external_ref, display_name }
       ↓
Survey Coder creates a sub-org and returns its child_org_id
       ↓
For every per-customer call, set `X-Connect-Org: <child_org_id>` so the request
operates on that sub-org's data isolated from your other customers

Managed sub-orgs are invisible from surveycoder.io — no login, no dashboard access. They exist only as a tenant-isolation boundary inside your platform.

Sandbox vs Live

Every Connect partner gets two sets of credentials:

• Sandbox (client_id_test + client_secret_test) — usage doesn’t roll into billing. Hard-capped at 1,000 credits/month by default. Use for integration testing.
• Live (client_id + client_secret) — real usage, real billing.

The environment is determined by which client_id you authenticate with. There’s no environment header to set; the tokens themselves carry the environment.

Note

Sandbox tokens are explicitly tagged in connect_usage.environment = 'sandbox'. The monthly billing cron only aggregates environment = 'live'. Spend caps are enforced separately per environment.

Billing

The Connect partner pays Survey Coder for aggregate usage at the Enterprise per-credit rate ($0.062/credit). No markup, no discount. You set your own pricing downstream.

• Aggregate, not per-customer. All of your live connect_usage rows for a month sum into one Stripe invoice on the 1st of the following month at 02:00 UTC.
• Post-pay, not prepay. Stripe auto-charges your card on file (added when you onboard).
• Spend caps protect you from runaway loops: a partner-wide monthly cap (default $1,000) and a per-data-org cap (default $500). Both configurable. Hits return 402 CONNECT_SPEND_CAP_REACHED.

Sandbox is not invoiced.

End-customer experience

The end-customer never sees Survey Coder’s billing surface. They only see:

• Your platform’s UI showing what your app does.
• A consent screen on surveycoder.io/oauth/authorize when they first connect their account (Standard flow only — Express customers don’t go through this).
• A “Connected apps” page at surveycoder.io/settings/connected-apps where they can review and revoke partner access.

The consent screen makes the cost model explicit (“Coding work performed by Talk2Data uses Talk2Data credits, not yours”). End-customers don’t need to top up Survey Coder credits to use your platform.

Scopes

Connect uses granular scopes (projects:read, coding:write, refinement:apply, etc.) rather than the legacy read/write/import triad. See OAuth scopes for the full catalog. Legacy scp_live_* keys keep working with their old scopes — the new granular system applies only to Connect Bearer tokens.

Becoming a Connect partner

Connect partners are onboarded manually for now. Email jorge@surveycoder.io with:

• Your platform name + URL
• Your expected use case (Standard, Express, or both)
• Estimated monthly volume
• Your privacy policy + ToS URLs

You’ll receive client_id + client_secret for both sandbox and live environments, plus the integration guide at Partner onboarding.

Reference

• OAuth scopes catalog
• Partner onboarding guide
• API reference: /oauth/* and /v2/connect/* endpoints in the API Reference.