Authentication

The Zoho Shifts API uses OAuth 2.0 to authorize and authenticate requests. It provides secure access to protect resources thereby reducing the hassle of asking for a username and password every time. Follow the steps listed here, to access Zoho’s APIs using OAuth 2.0

Note:You will have to use correct host URL of the data center in which you have account.

Data Center	Host URL
United States	https://accounts.zoho.com
Europe	https://accounts.zoho.eu
Australia	https://accounts.zoho.com.au

Step 1: Register Your Application

You will have to first register your application with Zoho's Developer console in order get your Client ID and Client Secret.

Follow the steps in register your application

Step 2: Generate Grant Token

You can generate grant token by redirecting the user to https://accounts.zoho.com/oauth/v2/auth with required parameters.

Parameters

scope

(Required)

Comma separated scopes for which the token to be generated.You can find list of scopes here.

client_id

(Required)

Client ID obtained in Step 1.

response_type

(Required)

Must be code.

redirect_uri

(Required)

Redirect URI given in Step 1.

state

An opaque string that is round-tripped in the protocol; ie., whatever value given to this will be passed back to you.

access_type

Any of online and offline. The online will give your application only the access_token which is valid for one hour. offline access_type will give your application an access_token as well as a refresh_token. Default is online.

prompt

Must be consent. If this parameter is included in the query, every time you generate an OAuth token, the user's consent approval will be mandatory.

On this request, you will be shown with a "user consent page".

Upon clicking “Accept”, Zoho will redirect to the given redirect_uri with code and state param. This code value is mandatory to get the access token in the next step and this code is valid for 60 seconds.

On clicking “Deny”, the server returns an error

For Self Client, you can generate this token in Zoho Developer console under Generate Code section.


https://accounts.zoho.com/oauth/v2/auth?scope=ZohoShifts.employees.READ,ZohoShifts.employees.CREATE&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&state=testing&response_type=code&redirect_uri=https://www.zylker.com/oauthredirect&access_type=offline

Once the end user grants the authorization request, Zoho Accounts sends an authorization grant code to the redirect URI client.

https://www.zylker.com/oauthredirect?code=1000.9c3a2a6a5362125efc9f7666224313b6.d44f4b5b63e71fc682cdf20c771efead

Step 3: Generate Access and Refresh Token

After getting code from the above step, make a POST request to https://accounts.zoho.com/oauth/v2/token with given params, to generate the access_token.

Parameters

code

(Required)

Code which is obtained in the above step.

client_id

(Required)

Client ID obtained in Step 1.

client_secret

(Required)

Client Secret obtained in Step 1.

redirect_uri

(Required)

Redirect URI given in Step 1.

grant_type

(Required)

Must be authorization_code.

In the response, you will get both access_token and refresh_token.

1. The access_token will expire after the given seconds in expires_in.

2. The refresh_token is permanent and will be used to regenerate new access_token, if the current access token is expired.


https://accounts.zoho.com/oauth/v2/token?code=1000.dd7e47321d48b8a7e312e3d6eb1a9bb8.b6c07ac766ec11da98bf6a261e24dca4&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf&redirect_uri=https://www.zylker.com/oauthredirect&grant_type=authorization_code


{
"access_token": "1000.c656b09869cfef3be0ca145e44143fa9.a11f43090a54d71dc0797ec92bf34b9e",
"refresh_token": "1000.4038qw5a8a5af1234ce920a45sx388a6.a450db33ca9e80701b1a23c8fe98e62e",
"api_domain": "https://www.zohoapis.com",
"token_type": "Bearer",
"expires_in": 3600
}

Generate Access Token From Refresh Token

Once the access_token is expired, your app will have to use the refresh token to generate a new access token. Make a POST request to https://accounts.zoho.com/oauth/v2/token with given params, to generate a new access_token.

Parameters

refresh_token

(Required)

refresh_token which is obtained in Step 3.

client_id

(Required)

Client ID obtained in Step 1.

client_secret

(Required)

Client Secret obtained in Step 1.

grant_type

(Required)

Must be refresh_token.


https://accounts.zoho.com/oauth/v2/token?refresh_token=1000.8ecd474019e31d52d2f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf&grant_type=refresh_token


{
"access_token": "1000.c656b09869cfef3be0ca145e44143fa9.a11f43090a54d71dc0797ec92bf34b9e",
"api_domain": "https://www.zohoapis.com",
"token_type": "Bearer",
"expires_in": 3600
}

Revoke Refresh Token

To revoke a refresh token, make a POST request to https://accounts.zoho.com/oauth/v2/token/revoke with the token

Parameters

token

(Required)

refresh_token which is obtained in Step 3.


https://accounts.zoho.com/oauth/v2/token/revoke?token=1000.8ecd474019e31d522f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc

Calling An API

Send the access_token as a header when you call a Zoho Shifts API.

Header name should be Authorization
Header value should be Zoho-oauthtoken {access_token}

$ curl https://shifts.zoho.com/api/v1/{org_id}/employees
-H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Scopes

Modules	Scopes
Employees	ZohoShifts.employees.CREATE ZohoShifts.employees.READ ZohoShifts.employees.UPDATE ZohoShifts.employees.DELETE
Shifts, Availability	ZohoShifts.schedules.CREATE ZohoShifts.schedules.READ ZohoShifts.schedules.UPDATE ZohoShifts.schedules.DELETE
Timesheets	ZohoShifts.timesheets.CREATE ZohoShifts.timesheets.READ ZohoShifts.timesheets.UPDATE ZohoShifts.timesheets.DELETE
Settings (Schedules, Positions, Job Sites)	ZohoShifts.settings.CREATE ZohoShifts.settings.READ ZohoShifts.settings.UPDATE ZohoShifts.settings.DELETE
Time Off	ZohoShifts.timeoff.CREATE ZohoShifts.timeoff.READ ZohoShifts.timeoff.UPDATE ZohoShifts.timeoff.DELETE