Skip to main content

This is a contributors guide and NOT a user guide. Please visit these docs if you are using or evaluating SuperTokens.

Plugin Interface

The plugin interface is an interface that defines how the core service can communicate with a database plugin.

For example, when the core's sign up API is called, and it needs to create a new user in the db, it would talk to the database plugin via a java interface - this interface is called the plugin interface.


This is actually a set of interfaces, one per recipe and per db type (SQL or noSQL). You can find this java project here.


It has its own versioning system with the format X.Y.Z.

  • The X value is incremented when there is a breaking change to the API spec. Breaking changes are defined by if an existing API is changed without / removed.
  • We increment the Y value for most changes - these include non breaking changes like adding new APIs
  • The Z value never really gets incremented, and can be ignored.

The core and each db plugin has a list of plugin interfaces they are compatible with. For example, see this file. These values determine if a core version and a db plugin version are compatible or not.

Why is this a separate Java project?#

  • If we had defined this interface as a part of the core, then the db plugin projects would have to be dependant on the core project. This would make it possible for them to (mis)use any part of the core project, which we want to avoid.

    Therefore, we have defined it as a separate project - the core and the db plugins are depandant on this project to communicate with each other.

  • We need to decouple the versioning of plugin interface and core anyway. If we made those versions the same, then even if there is a change in the core that's not related to the plugin interface, it would require changes in the db plugin (in terms of the version they support). So it's cleaner to have this as a separate project.

Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI