> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zoho Books

> Connect Zoho Books to Oleria to bring users and roles from your accounting organization into your identity and access graph.

Connect Zoho Books to Oleria to see who has access to your Zoho Books organization and with which role. Oleria reads users and roles from the Zoho Books API using OAuth credentials from a Zoho Self Client, so you can review access to your financial data and take action directly from Oleria.

<Note>
  This page covers Zoho Books. To connect your Zoho Directory through SCIM, see [Zoho](/integrations/zoho).
</Note>

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Zoho Books organization:

* **Accounts** - every user in the organization, with their name, email address, role, and status. Active users are enabled. Inactive users and users who haven't accepted their invitation yet are imported as disabled. Users with the Admin role are marked as administrators. Deleted users aren't imported.
* **Roles** - the role each user holds: the built-in **Admin**, **Staff**, and **Timesheet Staff** roles, and any custom roles. Every user holds exactly one role.

Oleria also records whether a user is limited to their assigned customers or vendors.

Oleria refreshes this data on its [regular sync schedule](/integrations/overview#sync-model).

<Note>
  Oleria doesn't import customers, vendors, invoices, bills, projects, or any other accounting data. This integration covers identity and access governance for people and roles only.
</Note>

## Prerequisites

* A Zoho Books user with the **Admin** role in the organization you want to connect. Zoho Books lets only admins list users and roles.
* Access to the Zoho API Console for the data center your organization is hosted in.
* Admin access to the Oleria workspace.

<Warning>
  Generate the credentials while signed in as a dedicated service-account user with the Admin role. The refresh token acts as the user who created it, so the connection stops working if that user is removed, marked inactive, or loses the Admin role.
</Warning>

## Find your data center and organization ID

<Steps>
  <Step title="Identify your data center">
    Your data center is the Zoho domain you sign in to. Use the matching addresses in the steps below and choose the matching **Data Center** in Oleria:

    | Zoho sign-in domain | Data Center in Oleria | API Console | Accounts server |
    | :- | :- | :- | :- |
    | `zoho.com` | United States (zoho.com) | `api-console.zoho.com` | `accounts.zoho.com` |
    | `zoho.eu` | Europe (zoho.eu) | `api-console.zoho.eu` | `accounts.zoho.eu` |
    | `zoho.in` | India (zoho.in) | `api-console.zoho.in` | `accounts.zoho.in` |
    | `zoho.com.au` | Australia (zoho.com.au) | `api-console.zoho.com.au` | `accounts.zoho.com.au` |
    | `zoho.jp` | Japan (zoho.jp) | `api-console.zoho.jp` | `accounts.zoho.jp` |
    | `zohocloud.ca` | Canada (zohocloud.ca) | `api-console.zohocloud.ca` | `accounts.zohocloud.ca` |
    | `zoho.com.cn` | China (zoho.com.cn) | `api-console.zoho.com.cn` | `accounts.zoho.com.cn` |
    | `zoho.sa` | Saudi Arabia (zoho.sa) | `api-console.zoho.sa` | `accounts.zoho.sa` |
  </Step>

  <Step title="Copy your organization ID">
    In Zoho Books, go to **Settings** -> **Organization Profile** and copy the **Organization ID**. It's a number, for example `10234695`.
  </Step>
</Steps>

## Create a Self Client and refresh token in Zoho

<Steps>
  <Step title="Create a Self Client">
    Sign in to the API Console for your data center as the Zoho Books admin. Select **Add Client** (or **Get Started**), choose **Self Client**, and select **Create**.
  </Step>

  <Step title="Copy the client credentials">
    Open the **Client Secret** tab and copy the **Client ID** and **Client Secret**.
  </Step>

  <Step title="Generate a grant code">
    Open the **Generate Code** tab and enter these scopes exactly:

    ```text theme={null}
    ZohoBooks.settings.READ,ZohoBooks.settings.CREATE,ZohoBooks.settings.UPDATE
    ```

    `ZohoBooks.settings.READ` lets Oleria import users and roles. `ZohoBooks.settings.CREATE` and `ZohoBooks.settings.UPDATE` are needed for the [remediation actions](#remediation-actions). Include all three unless you want a read-only connection.

    Choose a time duration, enter a description such as `Oleria`, and select **Create**. If Zoho asks you to choose a portal or organization, select the Zoho Books organization you're connecting. Copy the grant code.

    <Note>
      The grant code expires after the duration you chose, which can be as short as a few minutes. Complete the next step before it expires.
    </Note>
  </Step>

  <Step title="Exchange the grant code for a refresh token">
    On a trusted machine, run the following commands. Replace the accounts server with the one for your data center and the placeholders with your values. The first command prompts for the client secret without showing it or saving it to your shell history:

    ```bash theme={null}
    read -rs ZOHO_CLIENT_SECRET
    curl -X POST "https://accounts.zoho.com/oauth/v2/token" \
      -d "grant_type=authorization_code" \
      -d "client_id=YOUR_CLIENT_ID" \
      --data-urlencode "client_secret=$ZOHO_CLIENT_SECRET" \
      -d "code=YOUR_GRANT_CODE"
    ```

    Copy the `refresh_token` value from the response. Don't paste the response into tickets or chat, because it contains the refresh token.

    <Warning>
      Zoho returns the refresh token only once. Store it securely. If you lose it, generate a new grant code and repeat this step.
    </Warning>
  </Step>
</Steps>

<Note>
  The exact location of these settings can change over time. If the steps above don't match what you see, refer to Zoho's own API documentation.
</Note>

## Connect Zoho Books to Oleria

<Steps>
  <Step title="Open the integration">
    Go to your Oleria workspace, select **Integrations** -> select **Zoho Books**.
  </Step>

  <Step title="Complete the connection form">
    Select **Continue** and provide the following:

    | Field | Notes |
    | :- | :- |
    | Data Center | Required. The data center your organization is hosted in. Defaults to **United States (zoho.com)**. |
    | Organization ID | Required. The organization ID you copied from Zoho Books. |
    | Client ID | Required. The Client ID of your Self Client. |
    | Client Secret | Required. The Client Secret of your Self Client. |
    | Refresh Token | Required. The refresh token you generated. |
  </Step>

  <Step title="Confirm the connection">
    Select **Authenticate** to validate the credentials. Oleria checks that the refresh token works in the selected data center, that the organization ID belongs to that account, and that the token's user has the Admin role. Find the newly connected organization on the **Connected** tab of your Oleria **Integrations** page.
  </Step>
</Steps>

If **Authenticate** fails, check the **Data Center** first. A refresh token issued in one data center doesn't work in another.

<Note>
  You can connect each Zoho Books organization to Oleria once. To connect a different organization, add a new integration.
</Note>

## Verify the integration

Confirm the Zoho Books organization appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, you can review the discovered accounts and roles in your Oleria workspace.

<Note>
  If you revoke the refresh token or replace the Self Client in Zoho, update the integration in Oleria with the new values. To keep the stored client secret or refresh token when you edit other settings, leave that field empty. You can't change the organization ID of an existing integration.
</Note>

## Remediation actions

Oleria can take these actions in Zoho Books. Each one runs with the permissions of the user who created the refresh token:

* **Mark a user inactive** and **mark a user active**. These need the `ZohoBooks.settings.CREATE` scope. An inactive user keeps their role and history and can be reactivated.
* **Change a user's role**. This needs the `ZohoBooks.settings.UPDATE` scope. Because every Zoho Books user holds exactly one role, assigning a role replaces the user's current role. Reverting the action restores the previous role.

If the refresh token was generated without these scopes, the import still works, but the actions fail with a missing-permission error. Generate a new refresh token with all three scopes and update the integration.

Keep these limits in mind:

* Oleria won't mark inactive, or change the role of, the user who created the refresh token, because that would disconnect the integration.
* Users who haven't accepted their invitation yet can't be marked active or inactive.
* You can assign only roles that Oleria has discovered, which are roles held by at least one user.

## Known limitations

* Oleria doesn't import MFA or single sign-on settings for Zoho Books users. These are managed in Zoho Accounts and Zoho Directory.
* Oleria doesn't import activity. The Zoho Books activity log isn't available through the Zoho Books API.
* Oleria discovers roles from the users who hold them. A role that no user holds doesn't appear.
* Zoho Books has no user groups.
* Zoho limits API requests per organization. Oleria paces its requests to leave room for your other Zoho Books integrations.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.