Step 1: Register a new client

To integrate your application with Arattai Business Platform, you must register it with Arattai Business Platform:

1. Go to https://api-console.arattai.in/. If this is your first time registering a client application, click on GET STARTED.
   
2. Choose the required Client Type.
   
3. Enter the Client Name. This is the name of the application that you are registering with Arattai.
   
4. Enter the Homepage URL.
   
5. If you are registering a client-based, server-based, or mobile-based application, enter at least one Authorized Redirect URI. These are the URLs of your application to which Arattai Accounts will redirect you with the authorization code after successful authentication.
   
6. The URIs must start with https:// or http://. The path after the domain is flexible - for example: https://www.your-domain.com/oauth/redirect. The path does not need to be /callback.
   • You can enter multiple URIs, separated by commas.
   • You may use dummy values if you do not have a valid URI.
7. If you are registering a client-based application, you must enter at least one JavaScript Domain.
   • You can enter multiple domains, separated by commas.
   • Dummy values can be used if necessary.
8. Click on CREATE.
   

The client credentials will be displayed.

Step 2: Generating grant tokens and obtaining authorization code

To generate an authorization code, redirect your application's browser to Arattai's OAuth endpoint. Arattai utilizes the authorization code grant type, which requires a client application to obtain an authorization code to receive an access token.

The process for generating the authorization code varies based on the client type. Still, it is usually a one-time process, if you generate the access and refresh tokens before the code expires.

Generating the Authorization Code for a Server-Based Client Application

A server-based client application serves multiple users and requires user intervention during authorization.

1. To generate the authorization code for this type of client, use redirection-based code generation.
   The authorization flow is as follows:
   The client makes an authorization request to the resource owner by accessing the following URL:

Request URL:

Here's what each parameter means:

2. After the user clicks Accept, the request will be approved, and they will be redirected back to the client application's URI (specified in the previous step) with keys in the query string.

For example:

By following these steps, you will successfully generate the authorization code needed to obtain the necessary tokens for accessing the resources.

Error codes

Step 3: Generating access and refresh tokens

To exchange the authorization code for an access token and a refresh token, make a POST request to Arattai's OAuth token endpoint.

Once your client application receives the authorization code, you can exchange it for an access token by making the following request:

Request URL:

Example redirect_uri:
https://www.your-app.com/oauthredirect

Response:

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

Token Details

• access_token: This token is required to access resources corresponding to the scopes included in the authorization request. It will expire after a specific period, typically one hour
• refresh_token: This token is permanent and will be used to refresh the access token once it has expired. The refresh token is included in the response only if you passed the parameter access_type with the value offline when making the authorization code request for the first time.

Additional Token Information

• api_domain: The domain used by your app to make API requests to access protected resources.
• token_type: Indicates the type of access token generated. Access tokens issued by Arattai are Bearer tokens. When your app makes API requests to access protected resources, the access token must be included in the "Authorization" header.
  Syntax: Authorization: Bearer {access_token}
• expires_in: Indicates the duration (in seconds) until the access token expires. The lifespan of an access token is typically one hour (3600 seconds).

Error codes

Step 4: Get access token from refresh token

Access tokens expire in an hour. Client applications must make the following request and use their user's refresh token to generate a new access token. An access token typically expires after 3600 seconds (1 hour).

Before making API calls, or if you encounter an "expired token" error, you should obtain a new access token using the refresh token.

To Request a Refresh Token:

Make a POST request to the OAuth token endpoint with the following parameters:

Endpoint:

Response:

When you successfully request a new access token, you will receive the following response parameters:

• access_token: This is the token your app needs to access the resources, as defined by the requested scopes. This token is valid for 1 hour.
• api_domain: The domain to which your app needs to make API requests to access the protected resources.
• token_type: Indicates the type of access token generated. The access tokens issued by Arattai are Bearer tokens. When making API requests, include the access token in the "Authorization" header following this syntax:
  Authorization: Bearer {access_token}
• expires_in: Indicates the time (in seconds) until the access token expires, which is 3600 seconds (1 hour).

Step 5 : Revoking OAuth tokens

Why Revoke?

If a refresh token is no longer needed or seems to be compromised, it can be revoked and rendered invalid. This is done by making an API request. Once the revocation is successful, the refresh token can no longer be used to generate access tokens, and any existing access tokens that were created using this refresh token will also become invalid.

Programmatic Revocation

OAuth tokens can also be revoked by making a POST request to the endpoint /oauth/v2/token/revoke.

Both access tokens and refresh tokens can be revoked. If a refresh token is revoked, all access tokens generated using that refresh token will also be revoked.

Query Parameter:

token (required): The refresh token or access token that needs to be revoked.

Response:

• {"status": "success"} The token has been successfully revoked.
• 400 Bad Request: The token provided in the Request is invalid.