OAuth 2.0 workflow
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
Step 1: Register your app and get OAuth credentials
The first step in using OAuth authentication is registering your app with the Arattai API console. Once you register your client, you will get a Client ID and Client Secret for your application. These credentials are used to authorize your app's OAuth requests.
For detailed registration steps and a comparison of available client types, see Register your application.
Step 2: Obtain an access token
An access token is an OAuth token that allows access to Arattai's protected resources. The method for generating an access token depends on the type of application. For instance, server-based applications can use the authorization code flow, while client-based applications can utilize the implicit flow. However, in all cases, the access token is provided only after the user grants permission through consent. Access tokens are always assigned specific scopes, which are outlined in the request, and these scopes will be presented to the user during the permission request process.
Step 3: Access the resource using the access token
After your app has the access token, it can access Arattai's protected resources. Upon providing the access token to the resource server, your app will be granted access according to the scopes defined in the request. Arattai's OAuth implementation uses the Bearer authentication scheme; hence, when making API calls, the access token must be passed in the Authorization header with the prefix "Arattai-oauthtoken".
Step 4: Refresh the access token when it expires
Access tokens have a limited validity period, with a lifetime of only 1 hour. After this period, they expire and can no longer be used to access resources. However, if the app needs to access the resource for longer than 1 hour, it can retrieve and store a refresh token. This refresh token allows the app to generate a new access token whenever needed.
Step 5: Revoke unwanted tokens
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.
🔑 OAuth 2.0 Terminologies
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
The following are the terms you need to know before you start using the Arattai APIs.
| Term | Description |
|---|---|
| Protected Resources | A protected resource is any data or functionality within Arattai that requires authorized access. For example, when a client application needs to retrieve channel information through the Arattai API, the channels module serves as a protected resource. These resources are secured through OAuth authentication, ensuring that only authorized clients can access sensitive data and perform operations on behalf of users. |
| Resource Server | The server where the protected resources are stored, and to where the client must make API calls is called the resource server. In our case, the Arattai app which has the resource the client wants to access represents the resource server. |
| Resource Owner | The resource owner is the user who can grant the client permission to access the protected resources of their Arattai account. |
| Client | The application that needs access to the protected resource is called the client. The client can be a server-based application, a single page JavaScript application, a mobile/desktop application, or a non-browser limited input application. The client can make API requests to the resource server after successful authorization by the authorization server on behalf of the user. |
| Client ID | A unique identifier for your application which you can receive when registering your application in the Arattai API console. |
| Client Secret | A unique secret key for your application, which you receive when registering your application in the Arattai API console. The client secret is known only to your application and Arattai and must be kept confidential. (Client secret is not needed for client-based applications and will not be provided.) |
| Authorization Server | The server that grants access tokens and refresh tokens to the client on behalf of the resource owner is called the authorization server. In our case, Arattai Accounts is the authorization server. |
| Authorization Code | For server-based applications and mobile-based applications, access tokens cannot be generated directly. Instead, the client must first get an authorization code from the authorization server (Arattai Accounts), and then exchange it for an access token. The lifetime of an authorization code is only two minutes and it can be used only once. |
| Tokens | Description |
|---|---|
| Access Token | Access tokens are granted by the authorization server (Arattai Accounts) and are used by the client to access protected resources. A token contains information about the user and the granted scopes, telling the resource server that the bearer has been authorized to access the specified resource. The validity of an access token is 1 hour. |
| Refresh Token | Refresh tokens are used to generate a new access token after the old one expires. Refresh tokens are granted by the authorization server (Arattai Accounts) and can be stored by the client to generate access tokens whenever required. |
Note: Access tokens and refresh tokens are sensitive and must be kept confidential because they determine your level of access to APIs. Never share your tokens in public forums, public repositories, or in your website's client-side code, such as HTML or JavaScript. Exposing your tokens can lead to data theft, loss, or corruption.
Scopes
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
Scope determines which protected resource of an end-user a client has requested access to. A scope has three parameters: service name, scope name, and operation type.
The format to define a scope is
scope = service_name.scope_name.operation_type
Operation type: CREATE, READ, UPDATE, DELETE, ALL
List of scopes available in Arattai:
| Scope | Description | Available Operation Types |
|---|---|---|
| Meetings | Grants permission to schedule, read, update, and cancel meetings in Arattai. | Arattai.Meetings.CREATE, Arattai.Meetings.READ, Arattai.Meetings.DELETE |
| Channels | Grants permission to read channels and send messages of various types in Arattai. | Arattai.Channels.READ, Arattai.Messages.CREATE |
| Stories | Grants permission to upload, read, and delete stories in Arattai. | Arattai.Stories.UPDATE, Arattai.Stories.READ, Arattai.Stories.DELETE |