Practice Manager

Authentication & API Keys

A firm API key is a clientId and secret that belong to one accounting firm. Every request is signed with the secret; the key’s scope and client list decide what the request may touch.

Getting a firm API key

A firm API key is created for a specific COUNT firm by one of that firm’s owners or admins. When the key is created, the firm chooses its scope (which resources it may read or write) and its client access (every client workspace, or a selected list).

To get a key for your firm, or for a firm you are building for, email support@getcount.com with the firm’s name, the scope you need and which clients the key should reach.

The secret is shown once

COUNT stores the secret encrypted and returns it only when the key is created or its secret is rotated. Keep it in a secrets manager, never in client-side code. Rotating the secret stops the old one working immediately.

Firm keys and Partner API credentials are not interchangeable: a Partner API clientId gets 401 on /firm-partners, and a firm key gets 401 on /partners.

Signing requests

Practice Manager requests use the same HMAC-SHA256 scheme as the Partner API. Send three headers on every request:

HeaderValue
x-client-idYour firm key’s clientId.
x-timestampCurrent Unix time in seconds. Must be within 5 minutes of COUNT’s clock.
x-signatureLowercase hex HMAC-SHA256 of the base string below, keyed with your secret.
Base string
METHOD:path:timestamp:bodyHash

GET:/firm/details:1761041045:
POST:/firm/tasks:1761041045:<sha256 hex of the JSON body>
GET:/workspace/invoices:1761041045:
  • path is the request path with /firm-partners removed and no query string: /firm-partners/workspace/invoices?page=2 is signed as /workspace/invoices. Keeping the prefix is the most common signing mistake.
  • bodyHash is the hex SHA-256 of the exact JSON string you send, for POST, PUT and PATCH. Serialize compactly (JSON.stringify(body)) and send that same string. For GET and DELETE, and for writes with no body, it is empty — the base string ends with a colon.
  • Multipart uploads (documents) hash as an empty body: COUNT verifies the signature before it reads the file.
firmRequest (Node.js)
import crypto from 'node:crypto';

const BASE_URL = 'https://api.getcount.com';
const MOUNT = '/firm-partners';

// path is the full request path, e.g. '/firm-partners/workspace/invoices?page=2'.
export async function firmRequest({ method, path, body, workspaceId }) {
  const [pathname] = path.split('?');
  const signingPath = pathname.slice(MOUNT.length) || '/'; // '/workspace/invoices'
  const timestamp = Math.floor(Date.now() / 1000).toString();

  const hasBody = ['POST', 'PUT', 'PATCH'].includes(method) && body != null;
  const bodyString = hasBody ? JSON.stringify(body) : '';
  const bodyHash = hasBody ? crypto.createHash('sha256').update(bodyString).digest('hex') : '';

  const signature = crypto
    .createHmac('sha256', process.env.COUNT_FIRM_CLIENT_SECRET)
    .update(`${method}:${signingPath}:${timestamp}:${bodyHash}`)
    .digest('hex');

  const response = await fetch(BASE_URL + path, {
    method,
    headers: {
      'x-client-id': process.env.COUNT_FIRM_CLIENT_ID,
      'x-timestamp': timestamp,
      'x-signature': signature,
      ...(workspaceId ? { 'count-workspace-id': workspaceId } : {}),
      ...(hasBody ? { 'Content-Type': 'application/json' } : {}),
    },
    body: hasBody ? bodyString : undefined, // send exactly the string you hashed
  });
  return response.json();
}

The signature generator accepts /firm-partners paths, so you can check your implementation against it.

Who a request acts as

A key-signed request acts as a member of the firm, and COUNT records that member as the author of anything the request creates. For firm routes it is the firm’s owner — or, if the firm has no active owner, its first admin. In a client workspace, it is that member if they belong to the workspace, and otherwise the first firm member who does. That member’s role in the workspace governs role-restricted actions such as approving bills.

Per-user authorization is not available yet

The API also supports an OAuth flow in which a specific firm member authorizes your app and requests carry their bearer token. Its consent screen has not shipped, so this documentation covers key-based access only.

Scopes

A key’s scope is a list of grants. <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.

ResourceCovers
firmFirm details, clients and members; write creates client workspaces
tasksFirm tasks, and Tasks in client workspaces
time-entriesFirm time entries, and Time Entries in client workspaces
projectsFirm projects, and Projects in client workspaces
customersCustomers
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
invoicesInvoices, credit memos and recurring invoice templates
billsBills and vendor memos
transactionsTransactions
accountsChart of accounts, account sub-types and opening balances
journal-entriesJournal entries
productsProducts and services
tagsTags
peoplePeople
documentsDocuments and document types
expense-receiptsExpense receipts
reportsReports and workspace stats
budgetsBudgets
fixed-assetsFixed assets, asset types and depreciation rates
reconciliationsReconciliations
connectionsBank connections and connect links
webhooksWebhook subscriptions
workspaceWorkspace settings

Two report requests are treated as reads even though they are POSTs: running a report, unless the body sets save, and previewing a customer merge. Fetching an invoice’s public link is treated as a write.

Client access

A key reaches either all of the firm’s client workspaces, including clients added later, or a selected list. A key limited to selected clients:

  • sees only those clients in List client workspaces;
  • gets 403 on any other client workspace;
  • cannot use firm tasks, firm time entries or firm projects, because those span every client — it gets 403 there too;
  • cannot create client workspaces, because a new client could never be on its list.

Changes to a key’s scope or client list apply from the next request.

Errors

Errors share one body. Use statusCode and message to decide what to do, and include requestId when you contact support. Send your own x-request-id header and COUNT echoes it back as requestId.

Error body
{
  "message": "The API key does not allow this action.",
  "status": "Fail",
  "statusCode": 403,
  "isOperational": true,
  "customMsg": "Unable to authorize this request.",
  "requestId": "4f1c2e8a-6b0d-4a51-9e3f-2d7c8b1a0e94",
  "type": "UNKNOWN"
}
StatusmessageWhat to check
401UnauthorizedA signing header is missing, the timestamp is more than 5 minutes off, or the signature does not match. Check the signed path has no /firm-partners prefix and the body hash covers the exact bytes sent.
401Invalid clientId or Secret.The clientId is not a firm key.
403Firm partner app is inactive.The firm deactivated the key.
403The API key does not allow this action.The key’s scope lacks the resource or write access.
403This API key is limited to selected client workspaces, so it cannot use firm-wide endpoints.Firm tasks, time entries and projects need a key with access to all clients.
403This endpoint is not available to firm partner keys.The path under /firm-partners/firm does not exist.
400`Idempotency-Key` is not supported on this surface yet. Remove the header to proceed.Sent on a POST, PUT, PATCH or DELETE. Reads ignore the header. Drop it on writes.
429Too many requests.More than 100 requests in a minute for the firm user on the token (or for this clientId without one), or 10,000 for the app. Back off and retry after the Retry-After header.

Client workspace routes add their own access errors — see Working in Client Workspaces.