Introduction
Talqui's authentication system allows developers and operators to interact with both the REST API and the RTM API using three primary authentication methods. Each of these methods offers different levels of access and is designed to suit various use cases, such as operations on behalf of users, plugins, or other system entities. The system provides flexibility by supporting multiple authentication profiles, ensuring security and control over the data exchanged with the platform.
The three main authentication methods are: authentication on behalf of an operator using JWT Tokens, authentication on behalf of plugins using plugin tokens, and authentication on behalf of plugin connection. These methods allow you to manage access in a controlled manner, ensuring that each request has the appropriate scope, whether for an individual operator, an extension installed on the platform, or an specific tenant connection.
Talqui uses JWT Tokens and a custom made Basic Auth as the foundation for its authentication system. The exchange of information is handled securely in compliance with best practices, ensuring that authentication data is transmitted in an encrypted form and that each request has the appropriate scope for the required operation.
Authentication on Behalf of an Operator
The most conventional authentication method in Talqui is using JWT Tokens, where an operator connects on behalf of one or more tenants (customers or workgroups within the system). When authenticating as an operator, the system generates a JWT that grants the user access to all APIs and tenants they are associated with.
During the authentication process, a JWT is issued to the operator, allowing them to make requests to the API on behalf of all tenants associated with their account. This JWT is then used to access Talqui's APIs, ony reaching the REST API ( RTM API it's not allowed to that kind of authentication ). The token should be included in the authorization header of each request as follows:
Authorization: Bearer <your-jwt-token>
Once authenticated, the operator can retrieve the list of tenants they have access to through a specific endpoint, which returns the tenants associated with the JWT.
curl --location 'https://api.talqui.chat/tenants'
--header 'Authorization: Bearer <YOUR_AUTH_TOKEN>'
Authentication on Behalf of a Plugin
Talqui also supports authentication on behalf of plugins installed on tenants. A plugin is a system extension developed by third parties and installed on any tenant. Each plugin has a unique pluginID and pluginToken, which are used to authenticate with the API on behalf of the plugin.
The plugin authentication flow follows the Basic Authentication standard, where the pluginID and pluginToken are used to generate authentication credentials. When a plugin is installed on a tenant, it gains access to the APIs on behalf of that tenant. The tenant administrator is responsible for installing plugins, and once the plugin is installed, the developer can make requests to the API on behalf of that tenant.
Plugin authentication allows the developer to access data from all tenants that have installed the plugin. To authenticate, the plugin must include the pluginID and pluginToken in the authorization header as follows:
Authorization: Plugin base64(pluginID:pluginToken)
If you wish to develop your own plugin and learn more about creating and managing plugins in Talqui, refer to the documentation on creating plugins.
Additionally, to monitor which tenants have installed your plugin, you can consult a specific endpoint that tracks installations. For more details on this process, click here.
Authentication on Behalf of a Plugin Connection
In some cases, when you are responsible for a plugin in Talqui, you may need to make API requests not just on behalf of the entire plugin but for a specific plugin connection. A plugin connection is an entity that is automatically generated when a plugin is installed in a tenant. Each time a plugin is installed in a tenant, a new entry in Talqui’s system is created, resulting in a plugin connection object. This object also comes with its own plugin connection token.
When making API requests on behalf of a plugin connection, you use the pluginConnectionID and pluginConnectionToken in a Basic Authentication method. This method allows you to authenticate for that specific connection and make requests to Talqui’s APIs. The key difference here is that any request made using the plugin connection credentials will return data only for the specific tenant where the plugin is installed.
This method provides a strict relationship between the plugin and the tenant, ensuring that API requests will only retrieve data from the specific tenant where the plugin is connected. This can be useful for plugin developers who need to isolate data to a single tenant or integrate tightly with specific tenant environments.
The plugin connection authentication works similarly to the plugin-level authentication, but it is scoped strictly to one tenant. You authenticate using the plugin connection ID and plugin connection token in the following format:
Authorization: PluginConnection base64(pluginConnectionID:pluginConnectionToken)