OAuth 2.0 Authentication for Plugins

TypingMind Plugins support OAuth 2.0 authentication type. This help plugin developers create plugins that act on behalf of the user using the user’s account.

This authentication type make it easy to work with external services that requires OAuth.

Some example plugins you can create using OAuth authentication:

A Google Calendar plugin that allows the AI to read events from user’s Google calendar.

A Slack message plugin that all allows the AI to send a message to the user’s Slack channel.

Glossary

Term	Description
Plugin Developer	The person who create the Google Calendar plugin.
Admin User	The person who is the admin of a TypingMind instance (TypingMind Custom), this person have access to the admin panel to create new AI agents and install new plugins.
End User	The person who use the TypingMind instance, chat with the AI models, using the AI agents and plugins created by the Admin users.

💡

Looking for a step-by-step guide?

Read our tutorial: create a Google Calendar plugin with OAuth 2.0.

Overview and facts

Creating a plugin with OAuth requires the plugin developer to setup Authorization URL, Token URL, Scopes, Prompt, Access Type. These parameters are different depending on which OAuth provider is used.

When install a plugin with OAuth, the plugin will requires setting up OAuth Client ID and OAuth Client Secret. The admin user who install the plugin will need to set this up with their own OAuth app.

When the plugin is being used by the end users, they will need to authorize first. The authorization process is handled by TypingMind automatically.

Plugin developer can use the {OAUTH_PLUGIN_ACCESS_TOKEN} variable in their plugin source code as a placeholder for the user’s access token. If the user have not authorized or the access token has expired, the variable will hold an empty value.

Here is a diagram of the full flow (excluding the refresh token process):

Refresh Tokens

Access tokens are typically short-lived. A refresh token allows new access tokens to be obtained without reauthentication, ensuring a smooth user experience even when access tokens expire quickly (e.g., in one hour).

TypingMind manages refresh tokens internally if they are provided by the OAuth provider. However, whether a refresh token is issued depends on your OAuth configuration. To make sure refresh tokens are issued, it is often necessary to set specific parameters:

Access Type: Setting access_type=offline to explicitly request a refresh token.

Prompt: Many providers (like Google) only issue a refresh token the first time a user grants consent. Using prompt=consent ensures a refresh token is issued even if the user has previously authorized the app.

Note: Some OAuth providers automatically issue refresh tokens without requiring access_type or prompt, while others are strict about these parameters, or expect different values. Always consult the documentation of the specific provider.

Example OAuth Configuration:

json
"oauthConfig": {
	  "scopes": "https://www.googleapis.com/auth/calendar.readonly",
	  "tokenURL": "https://oauth2.googleapis.com/token",
	  "contentType": "json",
	  "authorizationURL": "https://accounts.google.com/o/oauth2/v2/auth",
	  "prompt": "consent",
	  "accessType": "offline"
}

OAuth in the TypingMind License version

If you are using the license version (individual version) at www.typingmind.com, everything is almost the same with some important difference:

You must provide the OAuth app by your own before using the plugin. You are acting as both admin user and end user (because there is no admin user in the TypingMind license version).

When authenticating, all steps of the OAuth authentication flow is run on the client side (your browser). The TypingMind license version does not have a server or a backend. Note that some OAuth providers may not allow this behavior. We tested the OAuth flow of Google and it seems to work on the browser side, but some other providers may not.

The TypingMind License Version is intended for single-user use. We don’t recommend sharing the license version to other users as they will have access to your OAuth Client Secret, which is not secure.

To share access to other users in a secure way, please use TypingMind Custom.

💡

TypingMind License Version does not have a built-in OAuth app for plugins. This is because having an OAuth app means that we (TypingMind) will have access to your Google account after you authorize, and we don’t want to have access your data. We are committed to make TypingMind License Version a truly static web app where all of your data is only stored locally on your device. By using your own OAuth credentials, you can still use all of the OAuth features without giving await access to your data.