OAuth2

The element denotes the OAuth2 based authentication and wraps up four stages,

• Authorization URL will generate grant token with client ID and possible scopes.
• Token URL helps to generate grant token using the access token.
• Refresh URL refreshes the access token once it is expired.
• Authentication URL is used in the server side to authenticate the token and identity of user.

Possible Locations

• Components
• Authentication Schema

Child Elements

• Description
• Authorization URL  required
• Token URL  required
• Refresh URL  required
• Authentication URL

Attributes

Example

In the trips resource, we have decided to use the oauth2 for authentication. So, write the authentication schema for it under the <resource> in the following way.

    

        
copy
        

            

        
    
    

         
 <oauth2 name="iam-oauth2-schema" visibility="internal" >
	<authorization-url path="https://accounts.travel_bureau.com/oauth/v2.0/auth">
		<operation method="get" name="Authorization Request" category="action">
			<description>To use the Zoho CRM APIs, the users must authenticate the application to make API calls on their behalf with an access token.</description>
			<argument name="scope" location="param">
				<description>Data that your application wants to access. Refer to Scopes for more details.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string"/>
					</structure>
				</content>
			</argument>
			<argument name="client_id" location="param">
				<description>Client ID(consumer key) that you obtained during client registration.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string"/>
					</structure>
				</content>
			</argument>
			<argument name="response_type" location="param">
				<description>Enter code.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string" values="code"/>
					</structure>
				</content>
			</argument>
			<argument name="access_type" location="param">
				<description>Enter access_type as online or offline.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string" values="offline,online">
							<description>If you want to generate the refresh token, set this value as offline.</description>
						</property>
					</structure>
				</content>
			</argument>
			<argument name="redirect_uri" location="param">
				<description>Callback URL that you specified during client registration.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string"/>
					</structure>
				</content>
			</argument>
			<response status="100" />
		</operation>
	</authorization-url>
	<token-url path="https://accounts.travel_bureau.com/oauth/v2.0/token">
		<operation method="post" name="Generate Access Token and Refresh Token" category="action">
			<description>OAuth2.0 requests are usually authenticated with an access token, which is passed as bearer token. To use this access token, you need to construct a normal HTTP request and include it in an Authorization header along with the value of Bearer.</description>
			<argument name="grant_type" location="param">
				<description>Enter the value as `authorization_code`.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string" values="authorization_code"/>
					</structure>
				</content>
			</argument>
			<argument name="client_id" location="param">
				<description>Specify client-id obtained from the connected app.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string"/>
					</structure>
				</content>
			</argument>
			<argument name="client_secret" location="param">
				<description>Specify client-secret obtained from the connected app.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string"/>
					</structure>
				</content>
			</argument>
			<argument name="code" location="param">
				<description>Enter access_type as online or offline.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string" values="offline,online">
							<description>Enter the grant token generated from previous step.</description>
						</property>
					</structure>
				</content>
			</argument>
			<argument name="redirect_uri" location="param">
				<description>Specify the Callback URL that you registered during the app registration.</description>
				<content>
					<encode type="text/plain" />
					<structure name="redirect_uri">
						<property type="string"/>
					</structure>
				</content>
			</argument>
			<response status="200">
				<content>
					<encode type="application/json" />
					<structure name="token structure">
						<property name="access_token" type="string">
							<description>Access token to access ZohoCRM APIs</description>
						</property>
						<property name="refresh_token" type="string">
							<description>Refresh token to obtain new access tokens</description>
						</property>
						<property name="expires_in" type="integer" values="3600">
							<description>Time in seconds after which the access token expires</description>
						</property>
						<property name="api_domain" type="string">
							<description>Domain name of the API. Use this domain in your requests to make API calls to Zoho CRM.</description>
						</property>
						<property name="token_type" type="string" values="Bearer">
							<description>Type of token obtained. "Bearer" indicates this is an access token.</description>
						</property>
					</structure>
				</content>
			</response>
		</operation>
	</token-url>
	<refresh-url path="https://accounts.travel_bureau.com/oauth/v2.0/token">
		<operation method="post" name="Refresh Access Token" category="action">
			<description>Access tokens expire after an hour of generation. To generate a new access token, use the refresh token you generated earlier.</description>
			<argument name="refresh_token" location="param">
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string" values="authorization_code"/>
					</structure>
				</content>
			</argument>
			<argument name="client_id" location="param">
				<description>Specify client-id obtained from the connected app.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string"/>
					</structure>
				</content>
			</argument>
			<argument name="client_secret" location="param">
				<description>Specify client-secret obtained from the connected app.</description>
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string"/>
					</structure>
				</content>
			</argument>
			<argument name="grant_type" location="param">
				<content>
					<encode type="text/plain" />
					<structure name="wrapper">
						<property type="string" values="refresh_token"/>
					</structure>
				</content>
			</argument>
			<response status="200">
				<content>
					<encode type="application/json" />
					<structure name="token structure">
						<property name="access_token" type="string">
							<description>Access token to access ZohoCRM APIs</description>
						</property>
						<property name="expires_in" type="string" values="3600">
							<description>Time in seconds after which the access token expires</description>
						</property>
						<property name="api_domain" type="string">
							<description>Domain name of the API. Use this domain in your requests to make API calls to Zoho CRM.</description>
						</property>
						<property name="token_type" type="string" values="Bearer">
							<description>Type of token obtained. "Bearer" indicates this is an access token.</description>
						</property>
					</structure>
				</content>
			</response>
		</operation>
	</refresh-url>
	<authentication-url path="https://accounts.travel_bureau.com/oauth/user/info">
		<operation method="get" name="Check Access Token" category="action">
			<response status="200">
				<content>
					<encode type="application/json" />
					<structure name="user info">
						<property name="First_Name" type="string" />
						<property name="Last_Name" type="string" />
						<property name="Display_Name" type="string" />
						<property name="ZUID" type="long" />
						<property name="Email" type="string" />
					</structure>
				</content>
			</response>
			<authentication location="param" type="oauth2" name="Authorization" scopes="AaaServer.profile.READ,email" />
		</operation>
	</authentication-url>
</oauth2>