API Keys

An API (application programming interface) is the door through which one program talks to another. An API key is a long secret string that the other program presents at that door to show it may read these books. Think of it as a key to one room, cut for one tenant.

A BizBooks360 key is read-only. In the page's words, it reads the whole ledger of these books and nothing else. It cannot add, change or delete anything, and it never reaches users, keys, billing or security settings. A program holding a key can fetch the company's details, the chart of accounts and three reports (trial balance, profit and loss, balance sheet); it can never post an entry.²

Why not give the program a user name and password instead? Three reasons:

1. Separation. A key belongs to a program, not a person. When the bookkeeper leaves, the program keeps working; when the program is retired, nobody's password changes.
2. One key per program. Each program gets its own key, so you can revoke one without touching the others. The page's own advice is exactly that.
3. Two-step verification stays on. A sign-in protected by two-step verification (Chapter 15.9) is meant for a person at a screen; a program cannot type the code, and switching the protection off for its sake would weaken the books.

Settings → Users and plan → API keys, the third tab beside Users and permissions and Access review (Chapter 15.7). For the owner the page has three cards: Create a key, Keys in use and Use a key. A set of books can hold up to 25 keys; a 26th is refused with These books already have 25 keys, the most allowed. Revoke a key that is no longer used before creating another.

A member sees no Create a key card, whatever their permissions say. In its place is a note.

The third card, Use a key, is the page you hand to whoever sets up the other program. It says where the program must knock and how.

Amounts are whole numbers in the currency's smallest unit: cents for US dollars, so 12345 is $123.45. A program that shows 11590 as a balance means $115.90.

1. 1

   Name the key after the software

   In Key name type Tax preparer import. Name it for the program, not the person: next year you will want to know at a glance what each key is for.

2. 2

   Create it and copy it at once

   Press Create key. A card appears at the top: The key "Tax preparer import" is ready, with the key in a box and a Copy key button. The card reminds you that the software sends the key in the X-API-Key header. Press Copy key (or select the key and press Ctrl+C), and paste the key into the tax program's connection settings straight away, together with the address from Use a key.⁴

1. 3

   Check that the key works

   Ask whoever set up the program to run its connection test, or try one request yourself from a terminal, with the example on the page. The practice books answered like this (the key itself replaced by YOUR-KEY; use your own address from Use a key in place of localhost:871):³

   curl -H "X-API-Key: YOUR-KEY" "http://localhost:871/api/v1/company"
   
   {"status":"SUCCESS","data":{"guid":"c30787d015da4ff7bd8371b291ede02e",
    "name":"Summit Gear Repair","currency":"USD","time_zone":"America/Los_Angeles",
    "accounting_method":"cash","fiscal_year_end":"2026-12-31"},
    "message":"The books of this key."}

   The same request without the header was refused with 401 and A valid API key is required in the X-API-Key header. A trial balance request for 11/05/2026 returned the accounts with their balances in cents, Accounts Payable among them at a credit of 11590, that is $115.90.

2. 4

   Know that it will not be shown again

   Open the page again, or press reload, and the key card is gone. The list still shows the key's name and date, and now the day it was last used. Its value is never displayed again, to anyone: the books keep only a scrambled fingerprint of it, not the key itself. If the key is lost before it reaches the program, revoke it and create another; nothing is lost but a minute.

1. 5

   A second key with the same name is refused

   The tax preparer asked for a key for a second computer, and the owner typed the same name again. The page refused: A key with this name already exists in these books. Choose another name. One name, one key, so that the list always says which program holds which key. A second program should get its own name, such as Tax preparer import -- office PC.

The return was filed; the tax program no longer needs the books until next season. Leaving the key active would leave a door open for months.

1. 1

   Press Revoke on the key's row

   The dialog warns that the program loses access as soon as the key is revoked, and that this cannot be undone: a new key can be created instead.

2. 2

   Confirm

   Press Revoke the key. The banner says The key "Tax preparer import" was revoked. Software that used it can no longer read these books. The list is empty again. A request with the old key now gets 401. Next season, create a new key with the same name: once the old key is revoked its name is free.

• [x] One key per program, named after the program.
• [x] The key was pasted straight into the program and kept nowhere else.
• [x] The program was given the address from Use a key and sends the key in the X-API-Key header, never in the address.
• [x] Old keys made before keys worked are revoked and replaced.
• [x] Every key in the list is in your key register with a reason to exist.
• [x] Keys for seasonal or retired programs are revoked.