Authentication

​

Authentication and Permissions

All Hyperspell API requests are authenticated using a Authorization: Bearer <token> header. You can generate an API key in the Dashboard.

Hyperspell is a multi-tenant platform, and you can have multiple users in your app — each with their unique data and query history. For that reason, in most cases you want to identify the user making the request. You don’t have to create users explicitly, you simply have to pass on the user id you have internally assigned to your user. There are two different ways of doing this:

​

Setting the user id in the Header

You can include the X-As-User: <user_id> header in your request. This will make Hyperspell assume that the user id is the one making the request. When using the SDK, you can set the user id like this:

client = Hyperspell(api_key="YOUR_API_KEY", user_id="user_id")

However, this requires you to send your API key in the header for every request. This is fine if you are using Hyperspell in a server-side environment where you can store the API key securely, but not if you are using Hyperspell in a client-side environment, for example in a web app or mobile app. For this reason, there is a second way to set the user id:

​

Using a User Token

A User Token is a JWT that is issued specifically for a user of your app, and restricts which data they can access and which actions they can perform. To obtain a user token, use the /auth/user_token endpoint or the SDK and pass the ID of your user:

curl --request POST \
  --url https://api.hyperspell.com/auth/user_token \
  --header 'Authorization: Bearer YOUR_APP_TOKEN' \
  --header 'Content-Type: application/json'

Afterwards, you can send the user token to your front end, where you can use it instead of the API key in the header:

const userClient = new Hyperspell({ apiKey: 'YOUR_USER_TOKEN'  });

See the API Reference for more information and usage examples. The /auth/user_token endopint is the only endpoint that is only accessible with an app token. If you do not use a backend to generate user tokens, or use a service like Clerk or Auth0 to manage your users, you can also configure them to provide a user token to your frontend.