Skip to main content
Tavryn authenticates API requests in two complementary ways: session cookies for interactive dashboard use, and a shared secret header for server-to-server and scheduled cron calls. Regardless of the authentication method, most endpoints also require a businessId to scope every operation to the correct tenant.

Dashboard & UI Authentication

When you use the Tavryn dashboard, authentication is handled automatically. Navigate to /auth and sign in with your email magic link or an OAuth provider (Google or GitHub). After a successful sign-in, a session cookie is set in your browser and sent with every subsequent API request — you do not need to manage tokens manually.
All standard API endpoints use session-cookie authentication. Your browser handles this transparently whenever you are signed in to the Tavryn dashboard. For server-side integrations that run without a browser session, use the CRON_SECRET mechanism described below.

Server-to-Server Authentication (CRON_SECRET)

The daily and weekly renewal evaluation pipelines run on a schedule and must be callable by Vercel Cron or your own scheduler without an interactive browser session. Tavryn authenticates these calls using a pre-shared secret. Two header formats are accepted — use whichever is most convenient for your scheduler. Option 1 — Authorization header (recommended)
Option 2 — Dedicated cron header
Example: trigger the daily cron pipeline
Keep your CRON_SECRET value private. Anyone who holds this secret can trigger the renewal evaluation pipeline across your deployment. Rotate it immediately if it is ever exposed.
Set the CRON_SECRET value as an environment variable in your Vercel project settings or in your .env.local file for local development. The GET /api/cron/daily and GET /api/cron/weekly endpoints use this mechanism — all other endpoints rely on session authentication.

The businessId Parameter

Tavryn is a multi-tenant system. Most API calls require a businessId — a UUID that scopes the request to your organization’s contracts, policies, wallet, and audit trail. Access controls are enforced server-side: even if you are authenticated, you cannot read or modify another organization’s data.
Pass businessId as a query parameter or in the request body depending on the endpoint. Refer to each endpoint’s individual reference page for the exact parameter location.
How to find your businessId
  1. Sign in to the Tavryn dashboard.
  2. Navigate to Settings.
  3. Your businessId is displayed on the settings page, or you can find it in the URL as ?businessId=<your-uuid>.
Copy that UUID and use it in your API calls. Example: fetch business settings

Authentication Flow Summary

HTTP Error Reference

When an API call fails due to an authentication or authorization problem, Tavryn returns one of the following status codes.
object
The request body or query parameters are invalid or missing a required field. Check the details field in the response for specific validation issues.
object
No valid session or Authorization header was found. Sign in at /auth or supply the correct CRON_SECRET.
object
You are authenticated but do not have permission to access this resource — for example, attempting to access a businessId that does not belong to your account.
object
You have exceeded the rate limit for this endpoint. The response body includes resetMs — the number of milliseconds until a request slot reopens in the sliding window.
object
An unexpected server-side error occurred. Retry with exponential backoff; if the problem persists, contact support.
Agent endpoints (/api/agent/*) and cron endpoints are rate-limited. POST /api/agent/run-now and GET /api/cron/daily are limited to 10 requests per minute. If you receive a 429 response, read the resetMs value from the response body and wait that many milliseconds before retrying.
HTTP 429 response body

Sign-In Methods

Tavryn supports the following sign-in methods:

Magic Link (Email OTP)

Enter your email at /auth/login and Tavryn sends a one-time sign-in link. No password required. After clicking the link you land on /onboard for first-time setup or the dashboard for returning users.

OAuth (Google / GitHub)

Authenticate with your existing Google or GitHub account. After completing OAuth consent you are redirected back to the Tavryn dashboard automatically.
If you are building an automated integration, use the CRON_SECRET pattern for server-side cron calls. Never embed privileged credentials in client-side code or commit them to source control.