Connect Zoho Books

fob-zb authenticates with a Zoho Self Client, a private OAuth client that belongs to your Zoho account. You create it once and get three values:

Value	Looks like	Lifetime
Client ID	`1000.ABCD…`	Until you delete the client
Client Secret	a 40-character string	Until you regenerate it
Grant code	`1000.abcd….efgh…`	Minutes, and single-use. fob-zb exchanges it for a refresh token that does not expire

The CLI can print these steps with links for every region:

fob-zb getting-started

1. Find your data center#

Zoho runs separate data centers, and a Self Client only works in the one where it was created. Check the address bar when you're signed in to Zoho Books:

Zoho Books address	Region flag	API Console
`books.zoho.com`	`com` (default)	api-console.zoho.com
`books.zoho.eu`	`eu`	api-console.zoho.eu
`books.zoho.in`	`in`	api-console.zoho.in
`books.zoho.com.au`	`com.au`	api-console.zoho.com.au
`books.zoho.jp`	`jp`	api-console.zoho.jp
`books.zohocloud.ca`	`ca`	api-console.zohocloud.ca
`books.zoho.com.cn`	`com.cn`	api-console.zoho.com.cn
`books.zoho.sa`	`sa`	api-console.zoho.sa

Use the API Console and --region value from the same row.

2. Create a Self Client#

Open the API Console for your region and sign in with the Zoho account that has access to your Zoho Books organization.
Select Get Started. If you already have clients, select Add Client instead.
Hover over Self Client, select Create Now, then select Create and OK.
Open the Client Secret tab and copy the Client ID and Client Secret.

Screenshot coming soon

Zoho API Console: choosing Self Client on the Get Started screen

Screenshot coming soon

Zoho API Console: the Client Secret tab showing the Client ID and Client Secret (values blurred)

You can reuse this one Self Client for every Zoho Books organization your login can see. See Organizations and tokens.

3. Generate a grant code#

In the same Self Client, open the Generate Code tab.
Fill in the form:

Field Value
Scope ZohoBooks.fullaccess.all
Time duration 10 minutes, the longest available
Scope description Anything, e.g. fob-zb on my laptop
Select Create. If Zoho asks, choose the Zoho Books organization to grant access to.
Copy the code. Use it within the time you selected. It works once only.

Field	Value
Scope	`ZohoBooks.fullaccess.all`
Time duration	`10 minutes`, the longest available
Scope description	Anything, e.g. `fob-zb on my laptop`

Screenshot coming soon

Zoho API Console: the Generate Code tab filled in with scope ZohoBooks.fullaccess.all and a 10-minute duration

Want read-only access?

For an AI agent that should only answer questions, use read scopes instead of ZohoBooks.fullaccess.all. See read-only scopes.

4. Add a profile#

Install the CLI first if you haven't: npm install -g @finopsbricks/fob-zb (details). Then run this, replacing the region, ID, secret and code with your own:

fob-zb config profiles add myorg \
  --region com \
  --client-id 1000.XXXXXXXX \
  --client-secret yyyyyyyy \
  --grant-code 1000.zzzzzzzz

fob-zb exchanges the grant code for a refresh token and stores everything in ~/.fob/fob-zb/config.yml. If your login can see exactly one organization, it picks it up automatically:

Exchanged grant code for a refresh token.
Saved Zoho Books credentials for profile 'myorg'.
Resolved organization for 'myorg'.

If you see Could not auto-resolve organization_id, your login can see several organizations. Pick one:

fob-zb organizations list
fob-zb config profiles add myorg --organization-id 8927xxxxxx

5. Check it works#

fob-zb config profiles current
fob-zb invoices list

config profiles current shows the profile, region and organization in use. If anything fails, the error message links to the matching troubleshooting section.

Using the library instead?#

Workers don't use profiles. Put the same values in environment variables. The refresh token is in ~/.fob/fob-zb/config.yml after step 4, or exchange the grant code yourself. See Use the library.