Setting up a Zoho API client for Zefty (US vs Canada data centres)

Connecting Zefty to Zoho Books takes about ten minutes, and most of that time is spent in the Zoho API console rather than in Zefty. The console is where you create a small "client" that lets Zefty read your bills and vendors and post vendor payments back, without ever seeing your Zoho password. This guide covers the whole process, including the one question that trips up most people: which data centre, .com or .ca, your Zoho account lives in.

What you are creating and why

Zoho Books does not accept a username and password from third-party software. Instead it uses OAuth: you register an application in the Zoho API console, Zoho gives you a Client ID and a Client Secret, and you approve a specific list of permissions once. From then on, Zefty holds a token that it refreshes automatically. You can revoke that token at any time from your Zoho account, and Zefty never stores a password.

The permissions Zefty asks for are deliberately narrow:

Nothing in that list lets Zefty edit bills, delete records or touch your customers.

Before you start: which Zoho data centre are you on?

Zoho runs separate data centres, and each has its own API console. If you create the client in the wrong one, the Client ID will not work, even though every other step looks fine.

The quickest way to know: open Zoho Books and look at the address bar.

• books.zoho.com means your account is in the US (global) data centre. Use https://api-console.zoho.com/. This is by far the most common case, including for Canadian companies.
• books.zoho.ca means your account is in the Canadian data centre. Use https://api-console.zoho.ca/. This applies to some Canadian-specific Zoho accounts.

Zefty asks for the same choice on its setup screen, labelled Zoho API Domain/Country, with the options United States (zoho.com) and Canada (zohocloud.ca). The console you use and the option you pick in Zefty must match.

Step 1: Find your Zoho Books organization ID

1. Sign in to Zoho Books.
2. Click the Settings gear icon.
3. Open Organization Profile.
4. Copy the Organization ID shown at the top of the page.

Keep it handy. Zefty needs it alongside the client credentials, because one Zoho login can own several Books organizations.

Step 2: Open the right API console

In a new browser tab, go to https://api-console.zoho.com/ or https://api-console.zoho.ca/, based on the check above. Sign in with the same Zoho account that owns the Books organization, or an administrator account for it.

Step 3: Create a Server-based Application

1. Click Add Client (on some accounts the button reads Create New Client or Get Started).
2. Choose the client type Server-based Applications. Do not pick "Self Client", "Web-based" or "Mobile"; only the server-based type supports the redirect flow Zefty uses.
3. Fill in the three fields exactly:
   • Client Name: Zefty
   • Homepage URL: https://zefty.ca/
   • Authorized Redirect URL: https://zefty.ca/authorize
4. Click Create.

The redirect URL is the one value that must be character-perfect. If it differs from https://zefty.ca/authorize in any way, including a trailing slash or http instead of https, Zoho will refuse to send you back to Zefty after you approve the permissions.

Step 4: Copy the Client ID and Client Secret

After creation, Zoho shows the Client Details page. It lists two values:

• Client ID: a long alphanumeric string that identifies the app. Copy it whole.
• Client Secret: a longer string that must stay confidential. Copy it whole as well.

Go back to the Zefty setup page and paste them into Zoho Client ID and Zoho Client Secret. Take care not to include a leading or trailing space; a copied space is the second most common cause of a failed connection, after the wrong data centre.

Step 5: Authorize Zoho Books

With the region, organization ID, Client ID and Client Secret filled in, click Authorize Zoho Books. You are sent to Zoho's own consent page, which lists the permissions described above. Click Accept.

Zoho redirects you to https://zefty.ca/authorize, Zefty exchanges the one-time code for tokens, and the first sync starts on its own: vendors first, then bills. Depending on how many bills you have, allow up to fifteen minutes. From that point on, Zefty syncs every night at 2 a.m. and whenever you click Sync with Zoho.

If authorization fails: delete the app and start over

Sometimes the flow is interrupted: a browser tab closed too early, a wrong region selected, a network hiccup, or a mistyped secret. When that happens, correcting the field and clicking Authorize again is not enough. Zoho allows the authorization handshake to complete only once per application. An app that went through a failed attempt will keep failing.

The recovery is short:

1. Return to the API console you used (api-console.zoho.com or api-console.zoho.ca).
2. Locate the Zefty client you created.
3. Click the Delete icon to remove it.
4. Create a new Server-based Application with the same three values (name, homepage URL, redirect URL).
5. Copy the new Client ID and Client Secret into Zefty and click Authorize again.

Because the credentials are new, the handshake starts fresh. If it fails a second time, the cause is almost always the data centre choice; double-check the Books URL.

Things to know after you connect

• The API fields lock after setup. Region, organization ID, Client ID and Client Secret are shown read-only in Zoho configuration afterwards. To connect a different Zoho Books organization, add a new organization in Zefty from the tenant menu.
• The consent can be revoked. In your Zoho account's connected apps, you can remove Zefty at any time. Zefty then stops syncing until you authorize again.
• The client is yours. It lives in your Zoho account, not in Zefty's. Nobody else can use it, and you can inspect or delete it whenever you like.

Key takeaways

• Check your Zoho Books URL first: .com means the US console, .ca means the Canadian console. The choice in Zefty must match.
• Create a Server-based Application named Zefty with the redirect URL https://zefty.ca/authorize, exactly.
• Zefty requests read access to bills, contacts and banking, and read/create access to vendor payments. Nothing more.
• If authorization fails, delete the app in the API console and recreate it. Zoho only lets each app complete the handshake once.
• The first sync runs automatically once you accept the permissions.

To see what happens after the connection is made, from the nightly sync to the payment posted back into Zoho Books, read the Zoho Books integration page. If you get stuck at any step, our support team can walk you through the console in English or French.