Third-party authentication

​

Rationale

Many apps don’t have their own dedicated backend and user management and rely on services like Clerk, Auth0, or Supabase to manage their users.

When you use Hyperspell’s SDK on a backend, you will use your secret API key to authenticate your app, and you can query a specific’s user data by simply passing the user’s ID.

If you user Hyperspell from a web or mobile app but still have your own backend, you would typically generate a user token on the backend (or server-side function), and then send this to your front end — User Tokens are temporary JWTs that are scoped to a specific user and signed with your app’s secret, and they can safely be used in your frontend.

However, if you want to use Hyperspell in an “unsafe” environment like a web app, but don’t have access to a backend that can securely store your API key, you can configure most third-party authentication services to create and sign a user token for you.

​

Using Clerk

Clerk is a popular authentication service that allows you to manage your users and their data.

We can share a secret with Clerk that is only known to your app and not used in your frontend. Clerk will use that secret to cryptographically sign a JWT that you can pass in to your Hyperspell backend.

The Hyperspell backend will then be able to verify that JWT was signed with your app’s secret and extract the user’s ID from it.

​

Getting your JWT Secret and App ID

You can get your JWT secret and App ID from the Hyperspell dashboard on your app’s Api Keys page:

​

Setting up Clerk

1. On the Clerk dashboard, go to your app’s settings and click on the “JWT Templates” tab in the left siderbar, right under “Session Management”.
2. Click on “New Template”, and choose “Blank”.
3. Name your template hyperspell.
4. Enable the “Custom signing key” toggle.
5. Choose “HS256” as the signing algorithm, and paste your JWT secret in the “Signing key” field.
6. Paste the following payload in the “Claims” field, replacing YOUR_APP_ID with your app’s id:

{
    "ref": "YOUR_APP_ID"
}  

7. Save your changes.

​

Using the JWT in your app

First, we create a custom Hyperspell client that injects the Clerk Hyperspell token into the request headers. Clerk stores that token in the active session, so we will have to pass this session to our Hyperspell client.

Then, we use the useSession hook to get the Clerk session object and pass it to our Hyperspell client:

import Hyperspell from 'hyperspell';
import { ActiveSessionResource } from "@clerk/types";

export const HyperspellWithClerk = async (session: ActiveSessionResource | null | undefined) => {
    const clerkToken = await session?.getToken({
		// Pass the name of the JWT template you created in the Clerk Dashboard
		// For this tutorial, you named it 'hyperspell'
		template: 'hyperspell',
    })

    const client = new Hyperspell({ apiKey: clerkToken });
    return client;
}