Getting Started

OAuth Consent Experience

What your users see when they connect COUNT to your app — and what you need to implement on the redirect back to your product.

Build trust with a clear UX

Partners who show a polished connect flow convert better. Match COUNT's consent language in your app and explain why you need access before redirecting users.

What the user sees

After you initiate OAuth, the user signs in to COUNT (if needed) and lands on a consent screen showing your app name and the workspace being connected. They choose Allow access or Cancel.

C

COUNT Partner Sign-in

Connect to Your App

Your App is requesting access to your COUNT workspace Acme Books.

This app will be able to

  • Read and write accounting data in this workspace
  • Access customers, invoices, transactions, and related records
  • Act on your behalf until you disconnect the app

Mock consent screen for documentation — not interactive.

Workspace vs firm OAuth routes

Workspace partner apps start at GET /auth2/authorize-intiate (legacy spelling — this is the live route). Firm or practice OAuth uses GET /auth2/firm/authorize-initiate instead. See API access credentials for a route summary.

Before redirecting

  1. Register your exact redirect URI in COUNT Partners — must match character-for-character including trailing slashes.
  2. Generate a cryptographically random state value and store it server-side.
  3. Choose the scopes your app needs.
  4. Call GET /auth2/authorize-intiate with your clientId, redirectUri, state, and scope.
  5. Redirect the user to the consent URL returned by the initiate endpoint.
Start authorization
GET /auth2/authorize-intiate
  ?clientId=<your clientId>
  &redirectUri=<your registered redirect URI>
  &state=<opaque value you generate>
  &scope=customers:read%20invoices:write

Scopes

scope is required. Send one or more grants separated by spaces, URL-encoded as %20 or +. <resource>:read allows GET requests on a resource and <resource>:write allows every method; write includes read. The bare grants read and write cover every resource, so scope=read%20write requests full access to the workspace. Request only what your app uses.

ResourceCovers
transactionsTransactions
accountsChart of accounts, account sub-types and opening balances
vendorsVendors
vendor-bank-accountsSupplier bank accounts (New Zealand); must be named, read/write and vendors do not include it
payment-batchesPayment batches and their bank files (New Zealand); must be named, read/write and bills do not include it
customersCustomers
peoplePeople
productsProducts and services
tagsTags
invoicesInvoices and recurring invoice templates
billsBills
journal-entriesJournal entries
budgetsBudgets
fixed-assetsFixed assets, asset types and depreciation rates
expense-receiptsExpense receipts
documentsDocuments and document types
reportsReports and workspace stats
tasksTasks
projectsProjects
time-entriesTime entries
workspaceWorkspace settings, GST settings, tax codes and the workspace event log
reconciliationsReconciliations
connectionsBank connections and connect links
webhooksWebhook subscriptions

Two POSTs count as reads: running a report, unless the body sets save, and previewing a customer merge. Fetching an invoice's public link counts as a write.

The token exchange and refresh responses return the granted scope. A refresh keeps the scope of the original consent; to change it, send the user through consent again. Apps that connected before scopes were introduced keep full access and do not need to reconnect.

Scope errors

The initiate request returns 400 A scope is required to authorize a partner app. when scope is missing, and 400 Unknown scope: … for a grant outside the table above. A call outside the granted scope returns 403 Insufficient OAuth scope for this action.

After the user approves

COUNT redirects to your registered URI with an authorization code and the same state you sent:

Successful redirect
https://your-app.com/oauth/callback?code=AUTH_CODE&state=YOUR_STATE

Exchange the code at POST /partners/grant-access-token (signed with HMAC, no Bearer token). Store the access and refresh tokens securely server-side.

Branding guidelines

  • Use Connect to COUNT or Sign in with COUNT for your button label.
  • Refer to the product as COUNT (all caps) in user-facing copy.
  • Explain which workspace data your app will access before the user leaves your site.
  • Provide a disconnect or revoke path in your app settings after connection.

Error and edge cases

Handle these cases
// User denied consent — no code is returned; handle missing code gracefully.
// Invalid or expired state — reject the callback (possible CSRF).
// User closed the window — your app should offer "Connect to COUNT" again.

See Errors & troubleshooting for HTTP error codes during token exchange.