Introduction

The Writer API is authenticated using OAuth2.0 protocol that allows you to share specific data with any application while keeping your usernames and passwords private. For example, a web application can use OAuth 2.0 in order to obtain permission from end users to create documents in their Writer account.

There are different types of tokens used in OAuth 2.0. Please take a look at the following basic terminologies before you get started with the authorization process.

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 Writer APIs.

Protected resources

The Writer's resources say a list of documents and folders.

Resource server

The Writer's server that hosts the protected resources.

Resource owner

Any end user who will grant access to the protected resources of your Writer account.

Authorization server

The server that provides the required credentials, such as, access and refresh tokens to the client. In our case, it will be the Writer's server.

Client

Client is the user application that sends request to the resource server to access the resources.

Authorization code

A temporary token created by the authorization server. This token will be sent to the client through the browser to get the access and refresh tokens.

Access Token

The token sent to the resource server to access the user's protected resources. The access_token will provide a secure access to Writer APIs and is used by applications to send requests to the connected app. An access_token is valid only for an hour and can be used only for the set of operations specified in the scope.

Refresh Token

This token is used to obtain new access_token. It has unlimited lifetime and is valid until it is revoked by the end user.

Scopes

You need to authenticate your application with appropriate key and scope. Scope is a variable parameter that controls access to a set of resources and operations that is allowed by an access_token. Your application can send one or more values in the scope parameter, during the access-token request. The access and refresh tokens are created with various specified scopes to ensure secure data access.

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=ZohoWriter.documentEditor.ALL

Available Scopes