SuperTokens SDKs & Libraries: Official & Community Integrations

SDKs overview

SuperTokens offers a suite of Software Development Kits (SDKs) designed to facilitate the integration of its self-hosted authentication solution into various application architectures. These SDKs are separated into backend and frontend components, allowing developers to manage authentication logic on the server side and user interfaces on the client side. The backend SDKs handle core authentication processes, such as user registration, login, session validation, and multi-factor authentication (MFA), while frontend SDKs provide pre-built UI components and client-side session management for popular frameworks.

The SDKs are built to provide developers with granular control over their authentication stack. This approach aligns with SuperTokens's focus on enabling open-source identity management and customizable authentication flows, ensuring that user data and logic remain within the developer's infrastructure. The ecosystem also includes community-contributed libraries, extending support to additional languages and frameworks beyond the official offerings.

Official SDKs by language

SuperTokens provides official SDKs for a range of popular backend languages and frontend frameworks. These SDKs are maintained by the SuperTokens team and offer comprehensive functionality for integrating authentication services. The backend SDKs are crucial for implementing server-side authentication logic, while the frontend SDKs simplify the client-side user experience.

The following table outlines the key official SDKs, their corresponding package names, typical installation commands, and their general maturity status as of the latest stable releases. For detailed documentation and specific version information, refer to the official SuperTokens documentation portal.

Installation

Installation of SuperTokens SDKs typically involves using the respective language's package manager. The process generally starts with setting up the SuperTokens core service, followed by installing the backend SDK in your server-side application and then the appropriate frontend SDK in your client-side application.

Backend SDK installation

For backend SDKs, you integrate the library into your server application's dependencies. For example, in a Node.js project, you would use npm or yarn. For Python, pip is used. Java projects commonly use Maven or Gradle for dependency management, requiring an entry in the project's pom.xml or build.gradle file. Go projects use go get to fetch the module.

Once installed, the backend SDK requires configuration, typically involving initialization with your SuperTokens core instance's address and defining the authentication methods you intend to support (e.g., email and password, social login, passwordless). The setup also includes defining API routes for authentication operations.

Frontend SDK installation

Frontend SDKs for frameworks like React, Vue, and Angular are installed via npm or yarn. These SDKs provide components and helper functions to build user interfaces for login, sign-up, and session management. They interact with the backend SuperTokens APIs to manage user sessions and implement authentication flows.

After installation, frontend SDKs are initialized within your application's main entry point, often requiring configuration similar to the backend, specifying the SuperTokens API base URL and enabling desired authentication UIs. Examples of frontend integration typically involve wrapping your application with a SuperTokens provider component and using provided hooks or components for different authentication functionalities.

Quickstart example

This example demonstrates a basic Node.js backend setup using the supertokens-node SDK and a React frontend using supertokens-auth-react for email-password authentication. This setup assumes a running SuperTokens core instance available at http://localhost:3567.

Node.js backend (index.js)

First, install the necessary packages:

npm install express supertokens-node cors

Then, set up your index.js:

const express = require('express');
const supertokens = require('supertokens-node');
const { middleware, errorHandler } = require('supertokens-node/framework/express');
const { EmailPassword } = require('supertokens-node/recipe/emailpassword');
const { Session } = require('supertokens-node/recipe/session');
const cors = require('cors');

supertokens.init({
    framework: 'express',
    supertokens: {
        // These are the connection details of the SuperTokens core
        connectionURI: 'http://localhost:3567',
        apiKey: '<YOUR_API_KEY>', // If you have an API key, use it here
    },
    appInfo: {
        appName: 'SuperTokens App',
        apiDomain: 'http://localhost:3001',
        websiteDomain: 'http://localhost:3000',
        apiBasePath: '/auth',
        websiteBasePath: '/auth',
    },
    recipeList: [
        EmailPassword.init(), // Initializes the EmailPassword recipe
        Session.init(), // Initializes the Session recipe
    ],
});

const app = express();

app.use(
    cors({
        origin: 'http://localhost:3000', // Your frontend domain
        credentials: true,
    })
);

app.use(middleware()); // SuperTokens middleware

// Your other API routes
app.get('/api/data', (req, res) => {
    // This route is protected by SuperTokens session
    res.json({ message: 'Protected data' });
});

app.use(errorHandler()); // SuperTokens error handler

app.listen(3001, () => {
    console.log('Backend running on http://localhost:3001');
});

React frontend (App.js)

First, install the necessary packages:

npm install supertokens-auth-react react-router-dom

Then, set up your App.js:

import React from 'react';
import supertokens from 'supertokens-auth-react';
import { getAuthWrapper } from 'supertokens-auth-react/hoc';
import { EmailPassword } from 'supertokens-auth-react/recipe/emailpassword';
import { Session } from 'supertokens-auth-react/recipe/session';
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import { SuperTokensWrapper } from 'supertokens-auth-react/lib/build/ui';

supertokens.init({
    appInfo: {
        appName: 'SuperTokens App',
        apiDomain: 'http://localhost:3001',
        websiteDomain: 'http://localhost:3000',
        apiBasePath: '/auth',
        websiteBasePath: '/auth',
    },
    recipeList: [
        EmailPassword.init(),
        Session.init(),
    ],
});

const AuthWrapper = getAuthWrapper(SuperTokensWrapper);

function App() {
    return (
        <AuthWrapper>
            <Router>
                <Routes>
                    {/* This route will render SuperTokens's login/signup UI */}
                    <Route path="/auth/*" element={supertokens.get // This route will render SuperTokens's login/signup UI */}
                    <Route path="/auth/*" element={supertokens.get // This route will render SuperTokens's login/signup UI */}
                    <Route path="/auth/*" element={supertokens.getRouterComponent()} />
                    <Route path="/" element={<Home />} />
                </Routes>
            </Router>
        </AuthWrapper>
    );
}

function Home() {
    return (
        <div>
            <h1>Welcome!</h1>
            <p>This is the home page. <a href="/auth">Login/Sign Up</a></p>
        </div>
    );
}

export default App;

This example sets up a basic authentication flow where the backend handles session management and the frontend provides the user interface for email and password login/signup. For more complex scenarios, such as social login or multi-factor authentication, additional SuperTokens recipes can be integrated into the recipeList.

Community libraries

While SuperTokens provides official SDKs for major languages and frameworks, the open-source nature of the platform encourages community contributions. These community-developed libraries extend SuperTokens's reach to additional programming languages, frameworks, or specific integration patterns not covered by the official offerings.

Community libraries can vary in their maturity, maintenance, and feature sets. Developers considering using a community library should review its documentation, GitHub repository activity, and community support to ensure it meets their project requirements. Examples of community-driven efforts might include integrations for:

• Other Backend Languages: Such as PHP (e.g., a SuperTokens PHP SDK developed by the community for frameworks like Laravel or Symfony).
• Deno: A runtime for JavaScript and TypeScript, where community efforts might create a dedicated SuperTokens client.
• Ruby: For Ruby on Rails or other Ruby-based applications.
• Kotlin: For backend services built with Kotlin, potentially leveraging the existing Java SDK or creating a more idiomatic Kotlin client.
• Specific Framework Integrations: Libraries that offer deeper integration with less common web frameworks or specialized environments.

The SuperTokens community typically shares these projects on platforms like GitHub and discusses them in forums or Discord channels. For a comprehensive list of community contributions and their status, developers can check the SuperTokens community documentation and GitHub organization, as these resources often link to external projects. It's also worth noting that many authentication standards, such as OAuth 2.0 and OpenID Connect, are supported by SuperTokens, allowing for broader compatibility even without a direct SDK for every language or framework.