---
title: "COUNT Partner API — authentication"
description: "How an agent authenticates to the COUNT Partner API: HMAC request signing plus a workspace-scoped OAuth access token."
canonical: "https://developers.getcount.com/AUTH.md"
---
# auth.md

Machine-readable authentication guide for the COUNT Partner API.

COUNT exposes two authentication surfaces, and they do not work the same way.

- **The MCP server** is a standard OAuth 2.0 resource with full discovery:
  RFC 9728 protected-resource metadata, RFC 8414 authorization-server metadata,
  RFC 7591 dynamic client registration, PKCE, and RFC 7009 revocation. An agent
  can authenticate here without a human writing any COUNT-specific code.
- **The REST Partner API** uses HMAC request signing plus a workspace access
  token from a partner-specific authorization-code exchange. It publishes no
  metadata document, requires a `scope` on every authorization, and its
  credentials are granted after review rather than self-serve.

COUNT does not implement the id-jag claim ceremony on either surface.

- **API base URL:** `https://api.getcount.com`
- **REST routes are prefixed** `/partners`
- **MCP server:** `https://api.getcount.com/mcp`
- **Human documentation:** https://developers.getcount.com/getting-started/authentication
- **OpenAPI:** https://developers.getcount.com/openapi.json

## Step 1 — Discover

### MCP surface

Fetch the protected-resource metadata, then the authorization-server metadata it
points at.

**1a.** `GET https://api.getcount.com/.well-known/oauth-protected-resource`

```json
{
  "resource": "https://api.getcount.com/mcp",
  "authorization_servers": ["https://api.getcount.com"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://developers.getcount.com/"
}
```

**1b.** `GET https://api.getcount.com/.well-known/oauth-authorization-server`

| Field | Value |
|---|---|
| `issuer` | `https://api.getcount.com` |
| `authorization_endpoint` | `https://api.getcount.com/mcp/oauth/authorize` |
| `token_endpoint` | `https://api.getcount.com/mcp/oauth/token` |
| `registration_endpoint` | `https://api.getcount.com/mcp/oauth/register` |
| `revocation_endpoint` | `https://api.getcount.com/mcp/oauth/revoke` |
| `scopes_supported` | `count.workspace` |
| `grant_types_supported` | `authorization_code`, `refresh_token` |
| `response_types_supported` | `code` |
| `code_challenge_methods_supported` | `S256` |
| `token_endpoint_auth_methods_supported` | `none`, `client_secret_post`, `client_secret_basic` |

An unauthenticated call to the MCP server returns a `WWW-Authenticate` challenge
pointing back at the protected-resource metadata, so a client that arrives
without discovering first is still told where to look.

### REST Partner API surface

No metadata document. The endpoints are fixed:

| Purpose | Method and path |
|---|---|
| Register a partner app | `POST /partners` |
| Read partner details | `GET /partners/{clientId}/details` |
| Exchange an authorization code | `POST /partners/grant-access-token` |
| Refresh a workspace token | `POST /partners/refresh-user-access-token` |

Partner credentials (`clientId`, `clientSecret`) are issued by COUNT and are not
self-serve. Request them through the partner programme:
https://developers.getcount.com/resources/partner-program

## Step 2 — Pick a method

COUNT supports two authentication surfaces. There is no anonymous access — every
route requires at least a partner signature.

| Method | Use when | What you get |
|---|---|---|
| `partner_hmac` | Your server calls the REST API directly | Proof the request came from your app |
| `partner_hmac + workspace_token` | You need a specific customer's accounting data | Access scoped to one workspace |
| `oauth2` (MCP) | An agent connects over MCP | Workspace-scoped session via consent screen |

### Scopes

The MCP surface publishes two scopes: `count.workspace` grants read and write
access to the workspaces the user selects during consent, and
`count.workspace.read` grants reads only. There are no per-resource MCP scopes.

The REST Partner API requires a `scope` on every authorization: one or more
grants separated by spaces. `<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 `read write` is full access
to the workspace. Request only what your app uses.

Resources: `transactions`, `accounts`, `vendors`, `customers`, `people`,
`products`, `tags`, `invoices`, `bills`, `journal-entries`, `budgets`,
`expense-receipts`, `documents`, `reports`, `tasks`, `projects`,
`time-entries`, `workspace`, `reconciliations`, `connections`, `webhooks`.

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. A call outside the granted scope returns 403
`Insufficient OAuth scope for this action.`

A token is bounded by its scope and by the workspace the user consented to.
A small number of routes additionally check a **permission held by the
consenting user** in that workspace. Today that is `PATCH /partners/workspace/gst-settings`, which requires
`manage_settings` and returns 403 without it. A connection consented by a user
who lacks the permission keeps working everywhere else.

Bootstrap routes (`POST /partners`, the two token routes, and partner details)
require only the HMAC signature. Every data route additionally requires a
workspace bearer token.

## Step 3 — Register

### MCP surface — `service_auth`, self-serve

Dynamic client registration is open (RFC 7591):

```http
POST https://api.getcount.com/mcp/oauth/register
Content-Type: application/json

{ "client_name": "Your agent", "redirect_uris": ["https://your-app.com/callback"] }
```

The token endpoint also accepts `none` as an auth method, so a public client
using PKCE needs no secret.

### REST Partner API surface — reviewed, not self-serve

Partner registration is not open. COUNT issues a `clientId` and `clientSecret`
after review, and you register your redirect URIs at the same time. A redirect
URI must be registered before it will be accepted in the consent flow.

Details: https://developers.getcount.com/getting-started/credentials

## Step 4 — Claim ceremony

A workspace owner authorizes your app through COUNT's hosted consent screen.

1. Send the user to the COUNT consent URL with your `clientId`, a registered
   `redirectUri`, a `state`, and a `scope`:
   `GET /auth2/authorize-intiate?clientId=…&redirectUri=…&state=…&scope=customers:read%20invoices:write`.
   A missing or unknown `scope` returns 400.
2. The user picks **one workspace** to grant access to and confirms.
3. COUNT redirects back to your `redirect_uri` with an authorization `code`.

There is no polling step — the code arrives on the redirect.

What the user sees: https://developers.getcount.com/getting-started/oauth-consent

## Step 5 — Exchange the assertion

```http
POST /partners/grant-access-token
x-client-id: <your clientId>
x-timestamp: <unix seconds>
x-signature: <hex HMAC-SHA256 of the base string>
Content-Type: application/json

{ "code": "<authorization code from the redirect>" }
```

Response:

```json
{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "accessTokenExpiresAt": "2026-06-06T12:00:00.000Z",
  "refreshTokenExpiresAt": "2026-07-06T12:00:00.000Z",
  "scope": "customers:read invoices:write",
  "workspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

The token is scoped to the single `workspaceId` returned. A partner with several
connected customers holds one token per workspace.

Refresh before expiry with `POST /partners/refresh-user-access-token`, sending
`{ "refreshToken": "..." }`. Every refresh returns a new refresh token with the
same scope, and the one you sent stops working, so store the new one. See
https://developers.getcount.com/guides/refresh-access-token

## Step 6 — Use the access_token

Every request carries both layers:

```http
x-client-id: <your clientId>
x-timestamp: <unix seconds, the same value used in the signature>
x-signature: <hex HMAC-SHA256 of the base string>
Authorization: Bearer <workspace access token>
Content-Type: application/json
```

The signature base string is:

```
METHOD:path:timestamp:bodyHash
```

- `METHOD` — uppercase HTTP method.
- `path` — the route **relative to the `/partners` mount**, e.g. `/customers`.
- `timestamp` — unix seconds, identical to the `x-timestamp` header.
- `bodyHash` — hex SHA-256 of the raw request body for `POST`, `PUT` and
  `PATCH`; an empty string otherwise. For a bodyless `POST`/`PATCH` (such as
  approve), send `{}` and hash `{}`; an empty `bodyHash` or the SHA-256 of an
  empty string is also accepted.

Sign the base string with your `clientSecret` using HMAC-SHA256 and send the
result hex-encoded. The `clientSecret` itself is never transmitted.

```js
import crypto from 'node:crypto';

function signRequest({ method, path, timestamp, body, clientSecret }) {
  const bodyHash = ['POST', 'PUT', 'PATCH'].includes(method)
    ? crypto.createHash('sha256').update(body ?? '').digest('hex')
    : '';

  const baseString = `${method}:${path}:${timestamp}:${bodyHash}`;

  return crypto.createHmac('sha256', clientSecret).update(baseString).digest('hex');
}
```

## Errors

| Status | Meaning | What to do |
|---|---|---|
| 401 | Missing or invalid HMAC signature, expired timestamp, or invalid bearer token | Re-check the base string, confirm the timestamp is current, refresh the token |
| 400 | Authorization request has no `scope`, or an unknown one | Send space-separated grants from the scope list |
| 403 | The credential cannot reach this workspace or resource | Confirm the user consented for this workspace and the token's `scope` covers the resource; some routes also require a permission the consenting user holds |
| 429 | Rate limit exceeded — 100 requests per minute per user of each app, or 10,000 per minute per app across all its users | Back off and retry after the `Retry-After` header |

Timestamps outside the accepted skew window are rejected as 401. Sign with the
same timestamp you send.

Full troubleshooting: https://developers.getcount.com/getting-started/errors

## Revocation

A workspace owner can revoke a connection from inside COUNT at any time, which
invalidates both the access token and the refresh token for that workspace.
After revocation, calls return 401 and the user must complete consent again.

Partners can revoke a stored connection through the Connections API:
https://developers.getcount.com/reference/connections

The MCP surface exposes an RFC 7009 token-revocation endpoint:

```http
POST https://api.getcount.com/mcp/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<access or refresh token>
```

It accepts `none`, `client_secret_post` and `client_secret_basic` as auth
methods. The REST Partner API has no equivalent endpoint — revoke a partner
connection through the Connections API or have the workspace owner disconnect it
inside COUNT. Neither surface implements RFC 8935 registration revocation.
