​
Persmissions

All Hyperspell API requests are authenticated using a Bearer token. There are two types of tokens:

App Token

Secret token that allow you to perform any action for any user. Never share this token with anyone. This is meant to be used in a server-side environment.

User Token

These are JWTs that are issued specifically for a user of your app, and restricts which data they can access and which actions they can perform.

When you create documents or collections with an app token, they are accessible by all users of your app. Conversly, documents and collections created with a user token are only accessible to the specific user that the token was issued to.

Likewise, when using an app token, you can query data from all users. That’s why it is important to keep the app token secret.

​
Generating Tokens

You can generate app tokens on the Dashboard. Tokens are only visible once, so make sure to save them in a secure location.

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'

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.

​
Using Hyperspell Connect

Hyperspell Connect is a feature that allows your users connect their accounts to Hyperspell. To do so, you need to open https://connect.hyperspell.com with the user token as a query parameter. Typically that involves putting a button in your app that looks like this:

<a href="https://connect.hyperspell.com?token=<user_token>">Connect your accounts</a>
<p>This app uses Hyperspell to securely connect your accounts.</p>

Hyperspell connect can be opened in a new tab, in an iFrame, or a web view for mobile apps. On the Hyperspell Connect page, your users will see a list of integrations you have enabled for your app, and they can choose which ones they want to connect to:

You can find out which integrations a user has connected to by calling the GET /auth/me endpoint with the user token or using the SDK. After a user has connected an integration, you can query the data right away.

Technically, the authorization flow with Hyperspell connect looks like this: