Authentication

Verso Fetch uses two authentication mechanisms depending on the context.

JWT links (user-facing flows)

The connect and manage pages are accessed via signed JWT links. Your backend generates a short-lived token using signLink() from @verso/core.

SignLinkOptions

Field	Type	Required	Description
`appId`	`string`	Yes	Your app identifier (e.g. `app_yourapp`)
`userRef`	`string`	Yes	Your internal user ID
`scopes`	`string[]`	Yes	Requested scopes (e.g. `["conversations:read"]`)
`purpose`	`"connect" \| "manage"`	Yes	Flow type
`expiresInSeconds`	`number`	No	TTL in seconds (default & max: 900 = 15 min)
`baseUrl`	`string`	No	Base URL for connect/manage pages (default: `https://connect.tryverso.ai`)

SignedLink return type

Field	Type	Description
`token`	`string`	The raw JWT string
`url`	`string`	Full URL: `${baseUrl}/${purpose}?token=${token}`

Example

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

// Connect link — user grants access to their LLM data
const connect = await signLink({
  appId:    "app_yourapp",
  userRef:  "user_123",
  scopes:   ["conversations:read"],
  purpose:  "connect",
}, process.env.VERSO_SECRET);

// Manage link — user views/deletes their data
const manage = await signLink({
  appId:    "app_yourapp",
  userRef:  "user_123",
  scopes:   ["conversations:read"],
  purpose:  "manage",
}, process.env.VERSO_SECRET);

Security properties

Algorithm: HS256 (HMAC-SHA256)
Max TTL: 15 minutes. Tokens with longer expiration are rejected.
Single-use: Each token contains a unique jti (JWT ID). The server inserts it into a used_jti table — duplicate usage is rejected with 403.
Scope validation: Requested scopes are checked against your app’s allowed_scopes configuration.

Available scopes

Scope	Description
`conversations:read`	Read imported conversation data
`conversations:write`	Write/update conversation data
`conversations:delete`	Delete conversation data
`profile:read`	Read user profile information

Bearer tokens (server-to-server)

The API endpoints (/api/conversations, /api/ingest-export, /api/purge) authenticate via your app secret as a Bearer token.

curl https://connect.tryverso.ai/api/conversations \
  -H "Authorization: Bearer YOUR_APP_SECRET" \
  -G -d "connectionId=uuid"

Authentication uses timing-safe comparison against your app’s secret stored in the vault.

Rate limiting

API endpoints are rate-limited to 60 requests per minute per app. The rate limiter is database-backed (atomic counter per app per minute bucket). Rate limit headers are included in every response:

Header	Description
`RateLimit-Limit`	Max requests per minute (60)
`RateLimit-Remaining`	Remaining requests in current window
`RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait (only on 429 responses)

Never expose your app secret in client-side code. All API calls should be made from your backend.

API Reference

Endpoints

JWT links (user-facing flows)

SignLinkOptions

SignedLink return type

Example

Security properties

Available scopes

Bearer tokens (server-to-server)

Rate limiting

​JWT links (user-facing flows)

​SignLinkOptions

​SignedLink return type

​Example

​Security properties

​Available scopes

​Bearer tokens (server-to-server)

​Rate limiting

JWT links (user-facing flows)

SignLinkOptions

SignedLink return type

Example

Security properties

Available scopes

Bearer tokens (server-to-server)

Rate limiting