# API keys and the REST API

> Create an API key for your own software, choose what it may do, understand test and live keys, and handle retries and rate limits when you call the REST API.

Source: https://support.billingmart.com/connections/api-keys
Updated: 2026-10-17 · Applies to: Web · Section: Connections: AI assistants and 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](https://support.billingmart.com/invoices/what-counts-as-a-send.md).
- **Every call is recorded** in the audit log with the key as the actor.

To be told when something happens, see [Webhooks](https://support.billingmart.com/connections/webhooks.md). To let an assistant in instead, see [Connect Claude, ChatGPT or Gemini](https://support.billingmart.com/connections/connect-an-assistant.md).