Authentication

Every Reporting API request must carry an Authorization: Bearer <key> header. The key resolves to a set of organization IDs the request is allowed to see; absence of authorization or a key that resolves to no orgs is rejected with 401.

The Bearer header

GET /reports/crr?from=2024-01-01&to=2024-12-31 HTTP/1.1
Host: api.montereyfinancial.app
Authorization: Bearer mk_your_key_here

The same shape works from any HTTP client:

curl -H "Authorization: Bearer mk_your_key_here" \
  "https://api.montereyfinancial.app/reports/crr?from=2024-01-01&to=2024-12-31"

import httpx

resp = httpx.get(
    "https://api.montereyfinancial.app/reports/crr",
    params={"from": "2024-01-01", "to": "2024-12-31"},
    headers={"Authorization": "Bearer mk_your_key_here"},
)
resp.raise_for_status()
print(resp.json()["items"][:3])

type CrrRow = {
  transaction_id: string;
  organization_id: string;
  account_id: string;
  type: string;
  amount_cents: number;
  effective_at: string;
  status: string | null;
};
type CrrPage = { items: CrrRow[]; page: { next_cursor: string | null } };

const res = await fetch(
  "https://api.montereyfinancial.app/reports/crr?from=2024-01-01&to=2024-12-31",
  { headers: { Authorization: "Bearer mk_your_key_here" } },
);
const data = (await res.json()) as CrrPage;
console.log(data.items.slice(0, 3));

Organization scoping

When the portal mints a key, an operator picks a set of organization IDs the key is allowed to see. Two patterns are common:

All-of-customer: one key covers every organization record a customer has registered with Monterey.
Subset: a key sees only the orgs a particular team within the customer is responsible for.

The server enforces this on every account- and transaction-shaped query — there is no path through the API that returns a row from an organization outside the allowlist. The same scope governs the payment-operations endpoints: a key can only see and manage payment methods belonging to borrowers on in-scope accounts, and autopay schedules on in-scope accounts.

401 vs 403

The Reporting API uses two distinct status codes:

Status	When	Body
`401 Unauthorized`	Missing / malformed / unknown / revoked / expired key	`{"detail": {"error_code": "missing_token" \| "invalid_token"}}`
`403 Forbidden`	`?organization_id=X` where X is not in the key’s allowlist	`{"detail": {"error_code": "organization_out_of_scope"}}`

An empty result is not the same as 403. If you query for a date range with no matching rows, you’ll get 200 with {"items": []}. A 403 means the query itself targeted an organization you can’t see.

Lookups by resource ID — /accounts/{id}, /payment-methods/{id}, /autopay/{id} — behave differently: an ID outside the key’s scope returns 404, the same as an ID that doesn’t exist. The API deliberately doesn’t distinguish the two, so a key can’t probe for the existence of resources it isn’t allowed to see.

Rotating a key

Treat the key like a password. When you need to rotate:

Mint a new key in the portal — choose the same organization allowlist.
Update your integration to use the new key.
Revoke the old key in the portal. Revoked keys begin returning 401 immediately.

There is no overlap window required — the new key starts working as soon as the portal commits the row, and the old key keeps working until you revoke it.

What we log

For every request we log the key prefix (the first 8 characters of the original API key, stored alongside the hash) and the resolved organization IDs. We never log the full API key, and the hash is one-way — losing your copy of the key means it cannot be recovered.

Overview

Endpoints

The Bearer header

Organization scoping

401 vs 403

Rotating a key

What we log

​The Bearer header

​Organization scoping

​401 vs 403

​Rotating a key

​What we log

The Bearer header

Organization scoping

401 vs 403

Rotating a key

What we log