# 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 |

<Video src="https://www.youtube-nocookie.com/embed/HFU6f7M5q0c" title="Creating a profile on fob-zb" />

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

```bash
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](https://api-console.zoho.com) |
| `books.zoho.eu` | `eu` | [api-console.zoho.eu](https://api-console.zoho.eu) |
| `books.zoho.in` | `in` | [api-console.zoho.in](https://api-console.zoho.in) |
| `books.zoho.com.au` | `com.au` | [api-console.zoho.com.au](https://api-console.zoho.com.au) |
| `books.zoho.jp` | `jp` | [api-console.zoho.jp](https://api-console.zoho.jp) |
| `books.zohocloud.ca` | `ca` | [api-console.zohocloud.ca](https://api-console.zohocloud.ca) |
| `books.zoho.com.cn` | `com.cn` | [api-console.zoho.com.cn](https://api-console.zoho.com.cn) |
| `books.zoho.sa` | `sa` | [api-console.zoho.sa](https://api-console.zoho.sa) |

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

## 2. Create a Self Client

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

<Screenshot alt="Zoho API Console: choosing Self Client on the Get Started screen" />

<Screenshot alt="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](/docs/zoho-books/orgs-and-tokens).

## 3. Generate a grant code

1. In the same Self Client, open the **Generate Code** tab.
2. 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` |

3. Select **Create**. If Zoho asks, choose the Zoho Books organization to grant access to.
4. Copy the code. Use it within the time you selected. It works once only.

<Screenshot alt="Zoho API Console: the Generate Code tab filled in with scope ZohoBooks.fullaccess.all and a 10-minute duration" />

<Callout type="info" title="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](/docs/zoho-books/orgs-and-tokens#read-only-scopes).
</Callout>

## 4. Add a profile

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

```bash
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:

```text
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:

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

## 5. Check it works

```bash
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](/docs/zoho-books/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](/docs/zoho-books/integration/library#credentials).