Connect Zoho

Supported Zoho services

What you will configure

1. Zoho Mail account
2. OAuth Self Client
3. Authorization code
4. Refresh token
5. Encrypted Agent Secret
6. Zoho Mail Skill

Zoho Mail account
        │
        ▼
Zoho OAuth Self Client
        │
        ├── Client ID
        ├── Client secret
        └── Read-only scopes
                  │
                  ▼
         Authorization code
                  │
                  ▼
       Access + refresh tokens
                  │
                  ├── Access token used temporarily
                  │   to find the Account ID
                  │
                  └── Refresh token saved in Agent Barn
                                  │
                                  ▼
                     Encrypted Agent Secret
                                  │
                                  ▼
                      Zoho Mail Skill + aai-cli

At the end of this guide, the Agent will have:

• A zoho_mail credential
• The built-in Zoho Mail Skill
• A generated zoho-mail-rest profile
• Read-only access to the selected Zoho Mail account
• Automatic access-token refresh during runtime requests

Before you begin

Use a dedicated mailbox when the Agent should not inherit a person’s complete inbox.

Official references:

• Zoho OAuth Self Client overview
• Zoho Self Client authorization-code flow
• Zoho Mail OAuth guide
• Zoho Mail API documentation
• aai-cli Zoho token-refresh reference

Check your Zoho data center

The current Agent Barn profile does not include a Zoho data-center field. Its runtime defaults are:

OAuth server: https://accounts.zoho.com
Mail API:     https://mail.zoho.com

This is the US/global .com Zoho data center. After signing in to Zoho Mail, check the domain in the browser.

Plan OAuth scopes

Request these two read-only scopes.

Enter the scopes as one comma-separated value:

ZohoMail.accounts.READ,ZohoMail.messages.READ

Do not request ALL, CREATE, UPDATE, or DELETE scopes for this integration. The current Agent Skill is read-only, so broader scopes do not add supported Agent capabilities.

Validation behavior

{
  "detail": "No validator available for zoho_mail"
}

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/zoho_mail/validate

aai-cli email messages list --limit 1 --profile zoho-mail-rest

Runtime behavior

When the Agent starts, Agent Barn:

1. Decrypts the Zoho Mail credential.
2. Stores the client secret and refresh token in the encrypted aai-cli secret store.
3. Generates the zoho-mail-rest profile.
4. Mounts the built-in Zoho Mail Skill.
5. Adds the configured integration to the Agent’s tool context.

The generated profile resembles:

[profiles.zoho-mail-rest]
provider = "zoho"
auth_type = "zoho_oauth"
email = "[email protected]"
account_id = "56218000000008002"
client_id = "1000.EXAMPLECLIENTID"
client_secret_secret = "zoho.client_secret"
refresh_token_secret = "zoho.mail_refresh_token"

The actual secret values are not embedded in the profile. The secret references are zoho.client_secret and zoho.mail_refresh_token.

For each request, aai-cli:

1. Reads the client ID, client secret, and refresh token.
2. Requests a fresh short-lived access token from Zoho.
3. Calls the Zoho Mail API using that access token.
4. Returns successful output as JSON.
5. Returns failures as structured JSON on standard error.

Encrypted refresh token
          │
          ▼
   aai-cli request
          │
          ▼
accounts.zoho.com OAuth token endpoint
          │
          ▼
Short-lived access token
          │
          ▼
mail.zoho.com API

Agent Barn does not store a temporary access token. No cron job or manual access-token refresh is required, and credential changes take effect after the Agent restarts.

Use a Shared Credential

Zoho Mail supports Organization-owned Shared Credentials. Use one when:

• Multiple Agents should read the same mailbox
• An Organization administrator should own OAuth rotation
• Agent operators should not handle the client secret or refresh token
• The same Zoho account ID applies to each attached Agent

To attach one:

1. Create or locate the Zoho Mail Shared Credential in the Organization.
2. Open the Agent’s Keys & integrations configuration.
3. Add Zoho Mail.
4. Switch from Manual credential to Shared Credential.
5. Select the intended credential.
6. Apply the change.
7. Restart the Agent if prompted.
8. Run a real aai-cli email command.

An Agent can use either a manual Zoho Mail credential or a Shared Zoho Mail Credential, not both simultaneously.

Live validation remains unsupported for the Shared Credential. Verify it from an attached Agent after restart.

Continue to Use shared credentials for the complete ownership model.

Rotate or remove the credential

Rotate the refresh token

1. Open the existing Self Client in the Zoho API Console.
2. Generate a new authorization code with both read-only scopes.
3. Exchange the new code for tokens.
4. Confirm that the response includes a new refresh token.
5. Replace the complete Zoho Mail credential in Agent Barn.
6. Restart the Agent.
7. Run messages list.
8. Revoke the old refresh token after the new credential works.

Rotate the client secret

If Zoho provides a new client secret:

1. Record the new client ID or secret.
2. Generate a new authorization code for that client.
3. Exchange it for a new refresh token.
4. Replace the Agent Barn credential as one unit.
5. Restart and verify the Agent.
6. Revoke the old OAuth credentials.

A refresh token is associated with the client that issued it. Do not combine a refresh token from one Self Client with another client’s ID or secret.

Remove the credential

Before removing Zoho Mail:

1. Remove or replace any assigned Skill that requires zoho_mail.
2. Stop the Agent, or use the website’s restart-aware apply flow.
3. Open Keys & integrations.
4. Mark the Zoho Mail credential for removal.
5. Apply the change.
6. Restart and verify the Agent.

Agent Barn blocks removal while an assigned Skill still requires the zoho_mail provider.

API reference

Add or replace a manual Zoho Mail credential

The Agent must be stopped when using the raw update endpoint.

PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}
Content-Type: application/json

{
  "secrets": [
    {
      "provider": "zoho_mail",
      "content": {
        "email": "[email protected]",
        "account_id": "56218000000008002",
        "client_id": "1000.EXAMPLECLIENTID",
        "client_secret": "REDACTED",
        "refresh_token": "REDACTED"
      }
    }
  ]
}

Attach a Shared Credential

{
  "shared_credentials": [
    {
      "shared_credential_id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

Remove the credential

{
  "removed_secret_providers": [
    "zoho_mail"
  ]
}

Credential operations require access to the Agent and the relevant update and secret-management permissions, including agent.secret.manage.

Troubleshooting

ZohoMail.accounts.READ,ZohoMail.messages.READ

aai-cli email messages list --limit 1 --profile zoho-mail-rest

Security practices

• Use a dedicated mailbox when possible
• Request only ZohoMail.accounts.READ and ZohoMail.messages.READ
• Do not request write or administrative scopes
• Protect both the client secret and refresh token
• Never store an access token, refresh token, authorization code, or client secret in source control
• Do not place secrets directly in shell commands saved to history
• Do not send OAuth values through Agent conversations
• Prefer Shared Credentials when administrators should own rotation
• Use separate OAuth clients for separate security boundaries
• Restart and test after every credential rotation
• Revoke unused refresh tokens
• Replace the Self Client immediately if its client secret is exposed
• Treat mailbox content as sensitive data when reviewing Agent logs and outputs

Next steps

• Connect Bitbucket
• Review Agent health and logs