Authentication

Verso Fetch has two credentials, for two audiences.

Credential	Who uses it	Where
App secret	Your backend	`signLink()` only, to sign connect and manage links
API key (`vsk_…`)	Your backend	`Authorization: Bearer` on every API call

The app secret is handed over at onboarding; API keys are created in the developer portal. Keep both server-side; neither belongs in a browser or a mobile app.

Signed links

The hosted pages (/start to connect, /manage to review and delete) are opened with a JWT your backend signs with the app secret.

import { signLink } from "@versoai/core";

const connect = await signLink(
  { appId: "app_yourapp", userRef: "user_123", scopes: ["conversations:read"], purpose: "connect" },
  process.env.VERSO_APP_SECRET!,
);
const manage = await signLink(
  { appId: "app_yourapp", userRef: "user_123", scopes: ["conversations:read"], purpose: "manage" },
  process.env.VERSO_APP_SECRET!,
);

Option	Required	Description
`appId`	Yes	Your app id
`userRef`	Yes	Your identifier for the user. Any string; it is returned in every webhook and is the key of `GET /api/connections`.
`scopes`	Yes	`["conversations:read"]`, the only scope today
`purpose`	Yes	`connect` opens `/start`, `manage` opens `/manage`
`expiresInSeconds`	No	Default and maximum 900 (15 minutes)
`baseUrl`	No	Default `https://connect.tryverso.ai`

Properties of a link:

Signed with HS256 using your app secret; Verso verifies it against the secret it holds for your app.
Expires after at most 15 minutes. An expired link shows an error page; sign a new one.
Single use. A connect link is consumed when the page starts the login flow, and a manage link when the user confirms the deletion, not when the URL is fetched: link previews in chat apps do not burn them, and the manage page can be reopened during its 15 minutes.
Scopes are checked against the scopes allowed for your app.

API keys

API keys start with vsk_ and are sent as a Bearer token.

curl -s "https://connect.tryverso.ai/api/connections?userRef=user_123" \
  -H "Authorization: Bearer $VERSO_API_KEY"

Several keys can be active at the same time, so rotation has no downtime: ask for a new key, deploy it, then ask us to revoke the old one. Only a hash of each key is stored; a lost key cannot be recovered, only replaced.

Using the app secret as a Bearer token still works for integrations built before API keys existed, but it is deprecated. New integrations must use an API key.

Rate limits

GET /api/connections, GET /api/users and GET /api/conversations are limited to 60 requests per minute per app. Every response carries the current state; a 429 also carries Retry-After.

Header	Meaning
`RateLimit-Limit`	60
`RateLimit-Remaining`	Requests left in the current minute
`RateLimit-Reset`	Unix timestamp when the minute ends
`Retry-After`	Seconds to wait, on `429` only

POST /api/purge and POST /api/ingest-export are not rate limited.

Getting started

Guides

Resources

Signed links

API keys

Rate limits

​Signed links

​API keys

​Rate limits

Signed links

API keys

Rate limits