Authentication

All Zoho Expense APIs need to be authenticated using an oauth token.

OAuth 2.0 is an open authorization protocol which grants third party applications limited access to user accounts on an HTTP service. The authentication and authorization process is facilitated only between the end-user and the HTTP service. Zoho APIs use OAuth 2.0 to provide dependable security for your application data. OAuth 2.0 delegates authorization and authentication for web and desktop applications, and mobile devices.

You can obtain an OAuth token by following the steps mentioned below:

Register your application
Get an authorization grant
Get an access token

1. Register your application

Before integrating Zoho APIs with your application using OAuth, you must register your application with Zoho. This can be done through the developer console of your Zoho account, where you will have to provide details regarding your application like Name , Website , Redirect URI, or Callback URL. Once the authorization is approved or denied, the user will be redirected to the callback URL specified at the time of registration.

Once your application is registered, the service will issue a client ID and a client secret. The Client ID is used by Zoho to verify the identity of the application and has a public visibility. The Client Secret is used to authorize the appropriate resources that can be accessed by the authenticated application. The Client Secret will be known only to Zoho APIs and the authenticated application.

2. Get an authorization grant

URL: https://accounts.zoho.com/oauth/v2/auth

Params:

scope=<Scopes for which token to be generated> Eg : ZohoExpense.expensereport.READ,ZohoExpense.advance.CREATE
client_id=<The client ID of the integrating app>
state=<An opaque string, it will returned as a URI parameter>
response_type=code
redirect_uri=<https://app.example.com/oauth (Redirect URI of your choice)>
access_type=offline (The allowed values are offline and online)

Available Scopes:

Scopes	Scope operations available
all	ZohoExpense.fullaccess.ALL Show Action All the scopes
expensereport	ZohoExpense.expensereport.UPDATE, ZohoExpense.expensereport.READ, ZohoExpense.expensereport.CREATE, ZohoExpense.expensereport.DELETE Show Action Expense module actions Expense Report module actions
approval	ZohoExpense.approval.CREATE Show Action Approve/Reject/Forward Reports
reimbursement	ZohoExpense.reimbursement.CREATE Show Action Reimburse Expense Reports
advance	ZohoExpense.advance.UPDATE, ZohoExpense.advance.CREATE, ZohoExpense.advance.DELETE Show Action Manage Advance Payments
users	ZohoExpense.users.UPDATE, ZohoExpense.users.CREATE, ZohoExpense.users.DELETE,ZohoExpense.users.READ Show Action Users and Roles
settings	ZohoExpense.orgsettings.UPDATE, ZohoExpense.orgsettings.CREATE, ZohoExpense.orgsettings.DELETE,ZohoExpense.orgsettings.READ Show Action Project related actions Customer related actions Categories related actions Currencies related actions Taxes related actions Organizations details

On calling the API, it will redirect to the redirect uri given with the authorization grant appended to it like below:

https://app.example.com/oauth?state=tempstate&code=1000.47b8xxxxxxxxxxxxxxxxxxxxxxxxf0d6.d3f4xxxxxxxxxxxxxxxxxxxxxxxxb6c0

3. Get an access token

After getting the authorization grant, post it to the below API to get the access token and the refresh token.

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

Params:

code=<Code obtained in the above step>
client_id=<The client ID of the integrating app>
client_secret=<Obtained during Client Registration>
redirect_uri=<Same URI that was used in the above step>
grant_type=authorization_code

Note: expires_in parameter in response contains expiry time of access_token in milliseconds.

Regenerating the access token with the refresh token

Once the access token has expired, it can be regenerated from the refresh token by making POST call to the API given below.

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

Params:

refresh_token=<Refresh Token obtained in the above step>
client_id=<The client ID of the integrating app>
client_secret=<Obtained during Client Registration>
redirect_uri=<Same URI that was used in the above step>
grant_type=refresh_token

Revoking a Refresh Token

A Refresh Token can be revoked by calling the API given below.

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

Params:

token = <Refresh token>


{
  "access_token": "1000.c656xxxxxxxxxxxxxxxxxxxxxxxx3fa9.a11fxxxxxxxxxxxxxxxxxxxxxxxx4b9e",
  "refresh_token": "1000.4038xxxxxxxxxxxxxxxxxxxxxxxx88a6.a450xxxxxxxxxxxxxxxxxxxxxxxxe62e",
  "expires_in_sec": 3600,
  "api_domain": "https://www.zohoapis.com",
  "token_type": "Bearer",
  "expires_in": 3600000
}


{
  "access_token": "1000.e896xxxxxxxxxxxxxxxxxxxxxxxx3fa9.a78fxxxxxxxxxxxxxxxxxxxxxxxx4b9e",
  "expires_in_sec": 3600,
  "api_domain": "https://www.zohoapis.com",
  "token_type": "Bearer",
  "expires_in": 3600000
}


{"status":"success"}