Using Hyperspell Connect
Hyperspell Connect is a feature that allows your users connect their accounts to Hyperspell. To do so, you need to openhttps://connect.hyperspell.com with a User Token as a query parameter. Typically that involves putting a button in your app that looks like this:
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.The User Token to identify your app and user.
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.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.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.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).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.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: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:
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 to connect an account using the GET /integrations/<integration_id>/link endpoint, which will generate an URL with a temporary token that can be used to connect an account. This endpoint is also available as a tool in the MCP Server, allowing your agents to programmatically connect an account on demand.