Skip to main content

​
Using Hyperspell Connect

Hyperspell Connect lets your users connect their accounts. Mint a User Token on your backend, exchange it server-to-server for a two-minute single-use code, and put only that code in the browser URL:
Never put the user token itself in a URL. Query strings can be retained by browser history, access logs, analytics, and referrer headers. Exchange codes expire after two minutes and are deleted on first redemption. 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:
Hyperspell Connect Example
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.

​
Configuration

There are several URL parameters that you can use to configure Hyperspell Connect.
​
string
required
A short-lived, single-use code returned by POST /oauth/token-exchange/issue.
​
string
If set, the Connect page will show a button to return to your app. You can also set the Redirect URI in the settings page on the Hyperspell dashboard. If the redirect_uri URL parameter is set, it will override the Redirect URI in the settings page.
​
boolean
default:false
If a redirect_uri is provided, the Connect page will automatically close and return to the redirect_uri when the user has connected all integrations. If providers is also set, autoclose will trigger when all specified providers are connected.
​
string
A comma-separated list of provider names to show on the Connect page (e.g., slack,google_drive,notion). Only the specified providers will be displayed, allowing you to show a subset of your configured integrations. Provider names are case-insensitive and use snake_case format. If omitted or empty, all configured integrations are shown.
​
string
Specify a custom font to use for the Connect page to match your app’s branding. You can use web-safe defaults such as system-ui (on iOS devices), sans-serif for the browser’s default font, or any font from Google Fonts, such as Roboto or Open+Sans+3 (Notice the + in the name instead of spaces).
​
string
Set to false to use redirect-based OAuth instead of popups. In this mode, clicking an integration navigates the current browser window through the OAuth flow and back, rather than opening a popup window. This is recommended for Safari compatibility, mobile web views, and iFrame embeds where popups may be blocked.
You can configure the link to your Connect page here:

​
Directly connecting accounts

Instead of using the Hyperspell Connect interface, you can also directly start the flow to connect an account. To do so, you first need to get the ID of the integration you want to connect to. You can find the ID of an integration in Dashboard, or you can programmatically get the ID of an integration using the GET /integrations/list endpoint. To connect an account, simply direct your user to the following URL:
Issue the code immediately before redirecting the browser. While the redirect_uri is optional, it’s recommended to set it to your app’s URL so that the user is redirected back to your app after the connection is complete. For the most seamless experience, add popup=false so the entire flow happens in the same browser window with no popups:
With popup=false, the user clicks “Connect Notion” in your app, sees the OAuth consent screen, authorizes, and is redirected straight back to your app. You can also generate a link using the GET /integrations/<integration_id>/link endpoint, which returns a URL carrying a one-time code.

​
How it works

As soon as the user has connected a data source, Hyperspell will automatically ingest and index data from that source. Technically, the authorization flow with Hyperspell connect looks like this: