---
title: "Practice Manager Authentication & API Keys · COUNT Partner API"
description: "Get a firm API key, sign Practice Manager requests with HMAC, and limit what a key can reach with scopes and client access."
canonical: "https://developers.getcount.com/practice-manager/authentication"
source: "https://developers.getcount.com/practice-manager/authentication"
---
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](mailto: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](https://developers.getcount.com/getting-started/authentication). Send three headers on every request:

| Header | Value |
| --- | --- |
| `x-client-id` | Your firm key’s clientId. |
| `x-timestamp` | Current Unix time in seconds. Must be within 5 minutes of COUNT’s clock. |
| `x-signature` | Lowercase hex HMAC-SHA256 of the base string below, keyed with your secret. |

Base string

```bash
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)

```javascript
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](https://developers.getcount.com/tools/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.

| Resource | Covers |
| --- | --- |
| `firm` | Firm details, clients and members; write creates client workspaces |
| `tasks` | Firm tasks, and Tasks in client workspaces |
| `time-entries` | Firm time entries, and Time Entries in client workspaces |
| `projects` | Firm projects, and Projects in client workspaces |
| `customers` | Customers |
| `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 |
| `invoices` | Invoices, credit memos and recurring invoice templates |
| `bills` | Bills and vendor memos |
| `transactions` | Transactions |
| `accounts` | Chart of accounts, account sub-types and opening balances |
| `journal-entries` | Journal entries |
| `products` | Products and services |
| `tags` | Tags |
| `people` | People |
| `documents` | Documents and document types |
| `expense-receipts` | Expense receipts |
| `reports` | Reports and workspace stats |
| `budgets` | Budgets |
| `fixed-assets` | Fixed assets, asset types and depreciation rates |
| `reconciliations` | Reconciliations |
| `connections` | Bank connections and connect links |
| `webhooks` | Webhook subscriptions |
| `workspace` | Workspace 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

```json
{
  "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"
}
```

| Status | message | What to check |
| --- | --- | --- |
| 401 | `Unauthorized` | A 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. |
| 401 | `Invalid clientId or Secret.` | The clientId is not a firm key. |
| 403 | `Firm partner app is inactive.` | The firm deactivated the key. |
| 403 | `The API key does not allow this action.` | The key’s scope lacks the resource or write access. |
| 403 | `This 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. |
| 403 | `This 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. |
| 429 | `Too 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](https://developers.getcount.com/practice-manager/client-workspaces#access-errors).
