OAuth 2.0 for v2 APIs-An Overview

The Zoho CRM API uses the OAuth2.0 protocol for authentication. It is an industry-standard protocol specification that enables third-party applications (clients) to gain delegated access to protected resources in Zoho via an API.

Why should we use OAuth2.0?

  • Clients are not required to support password authentication or store user credentials.

  • Clients gain delegated access, i.e., access only to resources authenticated by the user.

  • Users can revoke the client's delegated access anytime.

  • OAuth2.0 access tokens expire after a set time. If the client faces a security breach, user data will be compromised only until the access token is valid.

How OAuth2.0 works?

Terminologies

The following are some terms you need to know before you start using the Zoho CRM APIs.

Protected resources

The Zoho CRM resources, such as Leads, Contacts, Deals, etc.

Resource server

The Zoho CRM server that hosts protected resources.

Resource owner

Any end-user of your account, who can grant access to the protected resources.

Client

An application that sends requests to the resource server to access the protected resources on behalf of the end-user.

Client ID

The consumer key generated from the connected application.

Client Secret

The consumer secret generated from the connected application.

Authentication server

Authorization server provides the necessary credentials (such as Access and Refresh tokens) to the client. In this case, it will be the Zoho CRM authorization server.

Authentication code

The authorization server creates a temporary token and sends it to the client via the browser. The client will send this code to the authorization server to obtain access and refresh tokens.

Tokens

Access Token

A token that is sent to the resource server to access the protected resources of the user. The Access token provides secure and temporary access to Zoho CRM APIs and is used by the applications to make requests to the connected app. Each access token will be valid only for an hour and can be used only for the set of operations that are described in the scope.

Refresh Token

A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.

Scopes

Zoho CRM APIs use selected scopes, which control the type of resource that the client application can access. Tokens are usually created with various scopes to ensure improved security. For example, you can generate a scope to create or view a lead, or to view metadata and so on.
Scopes contain three parameters — service name, scope name, and operation type. The format to define a scope is scope=service_name.scope_name.operation_type

Example:

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL

Here, ZohoCRM is the service API name, modules is the scope name, and ALL is the operation type.

Available Scopes

Scope NameAssociated Methods
usersusers.all
orgorg.all
settingssettings.all, settings.territories, settings.custom_views, settings.related_lists, settings.modules, settings.variables, settings.tags, settings.tab_groups, settings.fields, settings.layouts, settings.macros, settings.custom_links, settings.custom_buttons, settings.roles, settings.profiles, and settings.currencies
modulesmodules.all, modules.approvals, modules.leads, modules.accounts, modules.contacts, modules.deals, modules.campaigns, modules.tasks, modules.cases, modules.events, modules.calls, modules.solutions, modules.products, modules.vendors, modules.pricebooks, modules.quotes, modules.salesorders, modules.purchaseorders, modules.invoices, modules.custom, modules.dashboards, modules.notes, modules.activities, modules.search
bulkbulk.all, bulk.read, bulk.create
notificationsnotifications.read, notifications.create, notifications.update, notifications.delete
coqlcoql.read

Group Scopes

Group scope provide complete access to all functions the user can perform on the record. For instance, a group scope can allow a user to read, create, update, and delete records in all modules.

Example:

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL,ZohoCRM.settings.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

In the above example, the user has access to all modules in the client ZohoCRM account.

Other examples are

  • scope=ZohoCRM.modules.READ(Read-only permission)

  • scope=ZohoCRM.modules.CREATE

  • scope=ZohoCRM.modules.UPDATE

  • scope=ZohoCRM.modules.DELETE

Separate Scopes

Separate scopes are used to provide access to data in a particular module without access to other modules.

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.leads.ALL,ZohoCRM.modules.deals.ALL,ZohoCRM.settings.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

The above scope gives the user access to only the leads and deals modules from the client Zoho CRM account.

Additionally, you can set specific permissions, like read, create, update or delete, for each module. For examples:

  • scope=ZohoCRM.modules.leads.READ(Read-only permission)

  • scope=ZohoCRM.modules.leads.CREATE

  • scope=ZohoCRM.modules.leads.UPDATE

  • scope=ZohoCRM.modules.leads.DELETE

Important

User Access Token must be kept confidential since it defines the type of API that you use. Do NOT expose your Access Token anywhere in public forums, public repositories or on your website's client-side code like HTML or JavaScript. Exposing it to the public may lead to data theft, loss or corruption.