Skip to main content
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.
This page covers Zoho Books. To connect your Zoho Directory through SCIM, see Zoho.

​
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.
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.

​
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.
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.

​
Find your data center and organization ID

1

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:
2

Copy your organization ID

In Zoho Books, go to Settings -> Organization Profile and copy the Organization ID. It’s a number, for example 10234695.

​
Create a Self Client and refresh token in Zoho

1

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.
2

Copy the client credentials

Open the Client Secret tab and copy the Client ID and Client Secret.
3

Generate a grant code

Open the Generate Code tab and enter these scopes exactly:
ZohoBooks.settings.READ lets Oleria import users and roles. ZohoBooks.settings.CREATE and ZohoBooks.settings.UPDATE are needed for the 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.
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.
4

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:
Copy the refresh_token value from the response. Don’t paste the response into tickets or chat, because it contains the refresh token.
Zoho returns the refresh token only once. Store it securely. If you lose it, generate a new grant code and repeat this step.
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.

​
Connect Zoho Books to Oleria

1

Open the integration

Go to your Oleria workspace, select Integrations -> select Zoho Books.
2

Complete the connection form

Select Continue and provide the following:
3

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.
If Authenticate fails, check the Data Center first. A refresh token issued in one data center doesn’t work in another.
You can connect each Zoho Books organization to Oleria once. To connect a different organization, add a new integration.

​
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.
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.

​
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.