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.
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 atGET /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
- Register your exact redirect URI in COUNT Partners — must match character-for-character including trailing slashes.
- Generate a cryptographically random
statevalue and store it server-side. - Choose the scopes your app needs.
- Call
GET /auth2/authorize-intiatewith yourclientId,redirectUri,state, andscope. - Redirect the user to the consent URL returned by the initiate endpoint.
GET /auth2/authorize-intiate
?clientId=<your clientId>
&redirectUri=<your registered redirect URI>
&state=<opaque value you generate>
&scope=customers:read%20invoices:writeScopes
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.
| Resource | Covers |
|---|---|
| transactions | Transactions |
| accounts | Chart of accounts, account sub-types and opening balances |
| vendors | Vendors |
| vendor-bank-accounts | Supplier bank accounts (New Zealand); must be named, read/write and vendors do not include it |
| payment-batches | Payment batches and their bank files (New Zealand); must be named, read/write and bills do not include it |
| customers | Customers |
| people | People |
| products | Products and services |
| tags | Tags |
| invoices | Invoices and recurring invoice templates |
| bills | Bills |
| journal-entries | Journal entries |
| budgets | Budgets |
| fixed-assets | Fixed assets, asset types and depreciation rates |
| expense-receipts | Expense receipts |
| documents | Documents and document types |
| reports | Reports and workspace stats |
| tasks | Tasks |
| projects | Projects |
| time-entries | Time entries |
| workspace | Workspace settings, GST settings, tax codes and the workspace event log |
| reconciliations | Reconciliations |
| connections | Bank connections and connect links |
| webhooks | Webhook 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 400A 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:
https://your-app.com/oauth/callback?code=AUTH_CODE&state=YOUR_STATEExchange 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
// 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.
