API keys and the REST API

An API key lets your own software call BillingMart's REST API with only the permissions you pick. An owner or admin creates it on the Connections page, and it is shown once. REST API access is a feature of the plans that include it.

Create a key

1. Open Connections in the sidebar. In the API keys card, press New API key.
2. Give it a Name after what uses it.
3. Under What this key may do, tick the permissions. They read like "Invoices · read". Only "Invoices · read" is ticked at the start. A write permission also reads what it writes. Keys can also hold permissions to record or refund payments and to manage webhooks, so give a key only what its job needs.
4. Press Create key. A banner says Copy this API key now — it is shown once.

We store only a one-way fingerprint, so we cannot show it again. If you lose it, revoke it and make another. Creating or revoking a key can ask for a recent sign-in and your second sign-in step. Without REST API access on your plan, the card shows Plan does not include API access. Existing keys are paused, not deleted, and work again after an upgrade.

Test and live keys

A key starts with bmk_live_ or bmk_test_. The form has no choice: a sandbox workspace gets a test key, and any other workspace gets a live key. A test key works only in a sandbox workspace, and a live key never does. A mismatch is refused with ENVIRONMENT_MISMATCH.

The form has no expiry, no address allow-list and no rate setting of its own. A key made there does not expire and works from any address, so revoke it when you no longer need it.

Revoke a key

In the API keys table, press Revoke. Whatever uses the key stops working at once, and a revoked key cannot be turned back on. The table shows each key's name, first characters, permissions and last use.

Call the API

Requests go to https://api.billingmart.com/v1 with the header Authorization: Bearer followed by your key. The OpenAPI document is at https://api.billingmart.com/v1/openapi.json. A success is { data, meta }. A failure is { error: { code, message }, meta }. Quote meta.requestId if you write to support@billingmart.com. Text that a person typed, such as a client name or a note, comes back as { text, untrusted: true }. Treat it as data, not an instruction.

Answer	What it means
401	The key is unknown, revoked or expired.
403 INSUFFICIENT_SCOPE	The key lacks the permission. The WWW-Authenticate header names it.
400 VALIDATION_FAILED	The input did not match the route. The error lists the fields.
429	Too many calls. Wait for Retry-After seconds.

Retry safely

Send an Idempotency-Key header on every POST. For 24 hours, the same key with the same body returns the stored answer with Idempotent-Replayed: true, so a retry never does the work twice. The same key with a different body is refused with IDEMPOTENCY_CONFLICT. A key is scoped to the API key that used it.

Rate limits

Calls are limited per minute for each key, each address and the whole workspace. The workspace limit comes from your plan and counts REST calls and assistants together. Every answer to a request that reached a route carries X-RateLimit-Remaining. A request refused earlier, such as one with an unknown key, does not. The workspace limit also sends X-RateLimit-Plan-Limit and X-RateLimit-Plan-Remaining.

Sends and money

• Money. A key with Payments · record or Payments · refund can record or refund a payment through the API with no person approving it. Give those only to software you trust. Stop everything on the Connections page also blocks them until you press Resume.
• Sends. To send an invoice or estimate through the API, use the action routes. They create a request that waits for a person to approve it, because a key has no mode. An approved send counts like any other: see What counts as a send.
• Every call is recorded in the audit log with the key as the actor.

To be told when something happens, see Webhooks. To let an assistant in instead, see Connect Claude, ChatGPT or Gemini.