Server-based applications - Overview
AI Tools
Open in ChatGPT
Open in ChatGPT to ask questions about this page
Open in Claude
Open in Claude to ask questions about this page
Copy as Markdown
Copy this page as markdown to use with AI assistants
View as Markdown
Open this page as markdown in a new tab
Open in ChatGPT
Open in ChatGPT to ask questions about this page
Open in Claude
Open in Claude to ask questions about this page
Copy as Markdown
Copy this page as markdown to use with AI assistants
View as Markdown
Open this page as markdown in a new tab
What are Server-Based Apps?
Server-based applications involve a clear separation between the front-end (client-side) and back-end (server-side) components. The application logic is executed on the server, and the generated content is sent to the browser for display.
These applications can securely store credentials, such as client secrets, on the server side and are referred to as "confidential clients" in OAuth terminology.
For server-based apps, the Authorization Code Flow is used to obtain access tokens. This flow involves exchanging an authorization code (received from the authorization server) for access tokens. Refresh tokens are also obtained in this process, enabling the server-based app to acquire new access tokens without requiring user intervention.
Authorization Code Flow
To get started, register your app in the Arattai API Console as a "server-based app." You will receive a Client ID and Client Secret, which are necessary for making API calls and obtaining OAuth tokens. Once you receive an access token, you can use it to access the protected resources of Arattai.
For added security, you can optionally use the authorization code flow with the Proof Key for Code Exchange (PKCE) extension. While PKCE is mandatory for mobile-based apps, it is also recommended for server-based apps.
Authorization Flow Steps
The authorization code flow to obtain an access token consists of the following steps:
- Request Authorization Code:
Make a GET request to the endpoint `oauth/v2/auth`, specifying the required scopes. The end user will be presented with the permissions your app is requesting. If the user grants access, an authorization code will be returned to the specified redirect URL. This code will be valid for 2 minutes. - Exchange Authorization Code for Tokens:
Using the received authorization code, make a POST request to the OAuth 2.0 token endpoint at `oauth/v2/token`. The Arattai authorization server will return an access token and a refresh token. The access token will be valid for 1 hour. - Access Protected Resources:
With the access token, you can call the Arattai APIs to access protected resources. When the access token expires after 1 hour, you can use the refresh token to obtain a new access token without requiring user intervention. To do this, send a POST request to the endpoint `oauth/v2/token` with the refresh token.
Revoking Tokens
User-Initiated Revocation:Users can revoke refresh tokens in the following ways:
- Connected Apps Management: Users can sign in to Arattai Accounts and go to the Connected Apps section to revoke the access they've granted for an app. This section is not available within the Arattai app's own account settings.
- Security Changes: Users can choose to revoke access for connected apps when they change their password or enable multi-factor authentication (MFA).
Refresh tokens can also be revoked programmatically by making a POST request to the endpoint `oauth/v2/token/revoke`. (Refer to the API Reference for more details.)
To get started, register your app in the Arattai API Console as a "server-based app." You will receive a Client ID and Client Secret, which are necessary for making API calls and obtaining OAuth tokens. Once you receive an access token, you can use it to access the protected resources of Arattai.
Note: Access tokens can also be revoked programmatically. When an access token granted via a refresh token is revoked, the associated refresh token will also be revoked.
Get Authorization Code
Request an authorization code from the Arattai authorization server. You will need to specify which scopes your app requires. Arattai will display the requested permissions to the user. If the user grants permission, an authorization code
will be sent to the redirect URL. This code is valid for 2 minutes.
Query parameters
| Parameter | Description |
|---|---|
| client_id | required
The unique ID of your application. You can find this in the Arattai API Console.. |
| response_type | required
Must be set to code. |
| redirect_uri | required
The URI to which the authorization server will redirect the browser with the authorization code. Must match the URI provided when registering the app in the API Console. Must start with http:// or https://. Example: https://www.yourapp.com/oauth/callback |
| scope | required
The scope(s) for the resources you want to access from the user's account. Multiple scopes can be separated by commas. These scopes will be displayed to the user when requesting consent. Example: Arattai.Channels.READ,Arattai.Messages.CREATE |
| access_type | Optional
Determines whether your app can refresh the access token without user intervention once it expires. - online: Only an access token will be provided (cannot be refreshed) - offline: A refresh token will also be provided, allowing your app to obtain new access tokens automatically Default value: online |
| prompt | Optional
If set to consent, the user will be prompted for consent every time your app requests access. If not included, the user will only be prompted on the first authorization. Value: consent |
Response parameters
After authenticating the user, Arattai will display the permissions your app is requesting. Once the user grants permission, the authorization code will be sent as a query parameter to the redirect_uri.
| Parameter | Description |
|---|---|
| code | The authorization code that can be exchanged for an access token. Valid for 2 minutes and can be used only once.
|
Error Codes
If the authorization request fails, an error will be returned to the redirect URI as a query parameter, or displayed to the user. Below are the possible error codes and their causes:
| Parameter | Description |
|---|---|
| access_denied | User rejected the request for access.
|
| invalid_client | The value of the parameter client_id is not valid.
The value of the parameter response_type is incorrect. It must be code. |
| invalid_response_type | The parameter client_id is missing.
The parameter response_type is missing. |
| invalid_scope | The parameter scope is either missing or the entered scope doesn't exist.
|
| invalid_redirect_uri | The parameter redirect_uri is either missing or the entered URI doesn't match the one configured in the API Console.
|
| 500 (Internal Server Error) | The server encountered an unexpected condition that prevented it from fulfilling the request.
|
| 400 (Bad Request) | The HTTP method used is incorrect. The request must use the GET method.
|
Best Practice : Always implement proper error handling in your redirect URI endpoint to gracefully handle authorization failures and inform users appropriately. RetryClaude does not have the ability to run the code it generates yet.
GET https://accounts.arattai.in/oauth/v2/auth
https://accounts.arattai.in/oauth/v2/auth?response_type=code&client_id=1000.GMB0YULZHJK411284S8I5GZ4CHUEX0&scope=Arattai.Channels.READ,Arattai.Messages.CREATE&redirect_uri=https://www.yourapp.com/oauth/callback&access_type=offline&prompt=consent
https://www.yourapp.com/oauth/callback?code=1000.abc123def456ghi789jkl012mno345pqr678stu901
Important: Store the authorization code securely and exchange it for an access token immediately, as it expires in 2 minutes.
Get access token
Exchange the authorization code for an access token from the Arattai authorization server.
Query parameters
| Parameter | Description |
|---|---|
| client_id | required
The unique ID of your application. You can find this in the API console. |
| client_secret | required
The unique secret for your app which is known only to your app and Zoho. You can find this in the API console. |
| grant_type | required
Must be set to authorization_code. |
| code | required
The authorization code you received from the authorization request. |
| redirect_uri | required
Must be the same URI provided when registering the app in the API Console. Must start with http:// or https://. Example: https://www.yourapp.com/oauth/callback |
Response parameters
| Parameter | Description |
|---|---|
| access_token | A token that your app uses to access the resources (as defined by the requested scopes). This token is valid for 1 hour. |
| refresh_token | A special token that your app can use to obtain a new access token once the current one expires. 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). |
| token_type | Indicates the type of access token that is generated. Arattai issues Bearer tokens. When your app makes API requests to access protected resources, include the access token in the "Authorization" header. |
| expires_in | Indicates the time (in seconds) until the access token expires. The lifetime of an access token is 1 hour (3600 seconds). |
Error Codes
If the authorization request fails, an error will be returned to the redirect URI as a query parameter, or displayed to the user. Below are the possible error codes and their causes:
| Parameter | Description |
|---|---|
| invalid_client | The parameter client_id is missing or its value is invalid.
• The value of the parameter grant_type is invalid. It must be authorization_code. |
| invalid_client_secret | The parameter client_secret is missing or its value is invalid.
|
| invalid_redirect_uri | The parameter redirect_uri is either missing or the entered URI doesn't match the one configured in the API Console.
|
| invalid_code | The parameter code is missing or its value is either invalid or already used.
• The value of the parameter grant_type is incorrect. It must be authorization_code. |
| invalid_redirect_uri | The parameter redirect_uri is either missing or the entered URI doesn't match the one configured in the API Console.
|
| 400 (Bad Request) | The HTTP method used is incorrect. The request must use the POST method.
The parameter grant_type is missing. |
POST https://accounts.arattai.in/oauth/v2/token
https://accounts.arattai.in/oauth/v2/token?client_id=1000.XMDEG1KBDO9SE2IFTMDFSRPYYJ5L0U&client_secret=1632308b34e2cf614fed922c5d6c4193c7778a5f13&grant_type=authorization_code&code=1000.406a3b53bad3f6824d4fb43108604cd7.a74aef3010243f0fae78111e2a673847&redirect_uri=https://www.yourapp.com/oauth/callback
{
"access_token": "1000.abcdef1234567890abcdef1234567890.abcdef1234567890abcdef1234567890",
"refresh_token": "1000.ghijkl0987654321ghijkl0987654321.ghijkl0987654321ghijkl0987654321",
"token_type": "Bearer",
"expires_in": 3600
}
Refresh access token
Use the refresh token to generate a new access token for the same set of scopes.
Using a refresh token, your app can create up to ten access tokens within a ten-minute window. If this limit is reached, access token creation will be blocked for the remainder of the ten-minute period. For more information, refer to
Token Limits.
Query parameters
| Parameter | Description |
|---|---|
| client_id | required
The unique ID of your application. You can find this in the API console. |
| client_secret | required
The unique secret for your app which is known only to your app and Zoho. You can find this in the API console. |
| grant_type | required
Must be set to refresh_token |
| refresh_token | required
The refresh token you received after making the initial access token request. |
Response parameters
| Parameter | Description |
|---|---|
| access_token | A token that your app uses to access the resources (as defined by the requested scopes). This token is valid for 1 hour. |
| token_type | Indicates the type of access token that is generated. Arattai issues Bearer tokens. When your app makes API requests to access protected resources, include the access token in the "Authorization" header. |
| expires_in | Indicates the time (in seconds) until the access token expires. The lifetime of an access token is 1 hour (3600 seconds). |
Error Codes
| Parameter | Description |
|---|---|
| invalid_client | The parameter client_id is missing or its value is invalid.
The value of the parameter grant_type is invalid. It must be authorization_code. |
| invalid_client_secret | The parameter client_secret is missing or its value is invalid.
|
| invalid_code | The parameter code is missing or its value is either invalid or already used.
The value of the parameter grant_type is incorrect. It must be authorization_code. |
| 400 (Bad Request) | The HTTP method used is incorrect. The request must use the POST method.
The parameter grant_type is missing. |
Sending Request Parameters
The parameters can be sent in one of the following formats:
Query StringAll parameters can be sent as a query string in the request URL.
Example:
https://accounts.arattai.in/oauth/v2/token?
client_id=1000.QVF8O5MXFUYATAQGJKEWUXJKZH7OOE
&grant_type=refresh_token
&client_secret=31a99ae27deff7fr34e419fe321b712a02cdedted7
&refresh_token=1000.3421ad0e1a6fe44663ea112b8b1c4fdf.cd38e645e3d7423651d17368855bc1c5
All parameters can be sent in the request body using the content type
application/x-www-form-urlencoded or
multipart/form-data.
Example:
client_id: "1000.QVF8O5MXFUYATAQGJKEWUXJKZH7OOE"
client_secret: "31a99ae27deff7fr34e419fe321b712a02cdedted7"
grant_type: "refresh_token"
refresh_token: "1000.3421ad0e1a6fe44663ea112b8b1c4fdf.cd38e645e3d7423651d17368855bc1c5"
Only the client_id and client_secret can be sent using this method. The credentials must be Base64 encoded and sent in the Authorization header.
Encoding format:
Base64encode(client_id:client_secret)Header format:
Authorization: Basic {Base64_encoded_credentials}Example:
Authorization: Basic MTAwMC5RVkY4TzVNWEZVWUFUQVFHSktFV1VYSktaSDdPT0U6MzFhOTlhZTI3ZGVmZjdmcjM0ZTQxOWZlMzIxYjcxMmEwMmNkZWR0ZWQ3
Note: When using Basic Auth Header, the
grant_type and refresh_token parameters must still be sent as query parameters or in the request body.
POST https://accounts.arattai.in/oauth/v2/token
POST https://accounts.arattai.in/oauth/v2/token?client_id=1000.GMB0YULZHJK411248S8I5GZ4CHUEX0&grant_type=refresh_token&refresh_token=1000.86a03ca5dbfccb7445b1889b8215efb0.cad9e1ae4989a1196fe05aa729fcb4e1
{
"access_token": "1000.abcdef1234567890abcdef1234567890.abcdef1234567890abcdef1234567890",
"token_type": "Bearer",
"expires_in": 3600
}