API reference

Quick start

1. The owner of the business opens API in the Basely panel and creates a key with the scopes your system needs.
2. Put the key in your server's environment. It is shown once.
3. Call /v1/me to check the connection, then the endpoints you need.

curl https://api.baselyapp.com/v1/me \
  -H "Authorization: Bearer bsk_live_..."

curl "https://api.baselyapp.com/v1/financial/summary?period=2026-09" \
  -H "Authorization: Bearer bsk_live_..."

Authentication

Send the key as Authorization: Bearer bsk_live_... on every request.

• The business comes from the key. There is no business id in the request, and a key never reaches another business.
• Test keys (bsk_test_) read the real business and validate writes, but never save them.
• Only the owner of the business creates, rotates and revokes keys. A key stops working when the person who created it is no longer the owner.
• Rotating keeps the old key working for a grace period you choose, so your server can switch without downtime.

Scopes

Each key carries only the scopes it was given. An endpoint without its scope answers 403 SCOPE_DENIED.

Endpoints

Base URL below. Every response has an x-request-id header.

Conventions

• Money is in integer cents with a currency. Dates are ISO 8601.
• Lists return object: list, data, has_more. Use limit (up to 100) and from/to to narrow them.
• Balances come from the books, which the bank keeps in sync by itself. Reading never asks the bank directly.
• A manual refresh from the bank (Fresh) is a separate action with its own monthly quota. Reading the API never spends one.
• Rate limits per key per minute: 120 reads, 30 writes, 20 reports. Over the limit: 429 with retry-after.

Errors

Errors have a stable code, a message for people and the request id. Write errors add reason and field.

{ "error": { "code": "SCOPE_DENIED", "message": "...", "scope": "invoices:write", "request_id": "req_..." } }

Webhooks

The owner adds the address of your system and picks the events. Deliveries retry for 24 hours.

Each delivery is signed with your endpoint secret in basely-signature, and carries basely-event-id so you can drop duplicates. Verify it like this:

import { createHmac, timingSafeEqual } from "node:crypto";

// header: basely-signature: t=<unix seconds>,v1=<hex>
export function isFromBasely(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}