OAuth Authentication:
The Zoho People API uses the OAuth2.0 protocol for authentication. It uses the Authorization Code Grant Type to obtain the grant token(code). This grant type allows you to share specific data with any application while keeping your usernames and passwords private. This protocol provides users with a secure and easy way to use authentication.
Why use OAuth2?
- You can revoke a customer's access to the application at any time.
- No need for disclosing credentials to clients.
- No information will be revealed even if the client is hacked since access tokens are issued to individual applications and not the client as a whole.
- Specific scopes can be applied to either restrict or provide access to certain data for the client. It would be different for each client application.
How does it work?
Terminologies
The following are some terms you need to know before you start using the Zoho People APIs.
Protected resources - The Zoho People resources, such as Employee details, Leave, Attendance, etc.
Resource server - The Zoho People 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 People authorization server.
Authentication code - A temporary token valid for two minutes is created by the authorization server and sent to the client via the browser. The client will send this code to the authorization server in order to obtain access and refresh tokens. It can only be obtained once
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 People 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 is 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. Refresh token is only generated once, but they do not expire. Ensure that the refresh taken is stored safely as it can be reused.
Note: 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 public may lead to data theft, loss or corruption.
Scopes
Zoho People 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 (See example below).
The format to define a scope is
scope=service_name.scope_name.operation_type
To know more about scopes, and for available scopes, click here.