API Overview & Authentication

    Zia Agents exposes APIs that let you trigger agents programmatically from external systems, custom functions, or your own applications. Before you can make any API call, you need to authenticate using Zoho's OAuth 2.0 flow.

    This article walks you through the authentication setup. Once that's in place, you can use the Agent API to interact with any deployed agent.

    What you'll need

    To authenticate and call the Agent API, you'll need the following credentials:

    • Client ID and Client Secret from the Zoho API Console
    • A Grant Token generated using your agent's OAuth scope
    • A Refresh Token obtained by exchanging the grant token
    • An Access Token generated from the refresh token (valid for one hour)

    The refresh token is permanent. Once you have it, you can generate new access tokens whenever you need them without repeating the full setup.

    Step 1: Find your agent's OAuth scope

    Go to your agent's details page and open the Integrate tab. You'll find the OAuth scope listed under Agent Info. Copy it. You'll need this in the next step.

    If you already have a refresh token, client ID, and client secret for this scope, you can skip ahead to generating an access token.

    Step 2: Get your client ID and client secret

    Head to api-console.zoho.com and create a Self Client if you don't already have one. Your Client ID and Client Secret are displayed here. These are permanent and won't change, so store them somewhere safe.

    Step 3: Generate a grant token

    In the API Console, go to the Generate Code tab and do the following:

    Paste the OAuth scope you copied in step 1. Set the duration to 10 minutes. Add a description for the scope and click Create.

    A grant token will be generated. This token is only valid for the duration you selected, so proceed to the next step before it expires.

    Step 4: Exchange the grant token for a refresh token

    Make a POST request to Zoho's OAuth endpoint with your credentials:

    
POST https://accounts.zoho.com/oauth/v2/token

Parameters:
  code           = {your grant token}
  client_id      = {your client ID}
  client_secret  = {your client secret}
 grant_type = authorization_code

    The response contains both a refresh token and an access token. The access token expires after one hour. The refresh token is permanent and can be used to generate new access tokens whenever needed.

    Store the refresh token securely.

    Step 5: Generate an access token

    Whenever you need a fresh access token, make a POST request using your refresh token:

    
POST https://accounts.zoho.com/oauth/v2/token

Parameters:
  client_id      = {your client ID}
  client_secret  = {your client secret}
  refresh_token  = {your refresh token}
 grant_type = refresh_token

    The response includes a new access token valid for one hour. Use this in the Authorization header of your API calls.

    What's next

    With authentication in place, you're ready to call the Agent API. See Agent API Reference for the full request format, headers, and parameters.

    PREVIOUS

    UP NEXT