> ## Documentation Index
> Fetch the complete documentation index at: https://tavryn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate API Requests to Tavryn

> How Tavryn authenticates API requests: session-based sign-in for browser clients, businessId for tenant scoping, and CRON_SECRET for server-to-server calls.

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.

> [!NOTE]
>
> 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)**

```http theme={null}
Authorization: Bearer <CRON_SECRET>
```

**Option 2 — Dedicated cron header**

```http theme={null}
x-cron-secret: <CRON_SECRET>
```

**Example: trigger the daily cron pipeline**

```bash theme={null}
curl -X GET "https://<your-deployment-url>/api/cron/daily" \
  -H "Authorization: Bearer <YOUR_CRON_SECRET>"
```

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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**

```bash theme={null}
curl -X GET "https://<your-deployment-url>/api/business/<YOUR_BUSINESS_ID>/settings"
```

## Authentication Flow Summary

| Scenario | Method | What to send |
| - | - | - |
| Dashboard / browser | Session cookie | Cookie set automatically after signing in at `/auth` |
| Server-to-server cron | Bearer token | `Authorization: Bearer <CRON_SECRET>` header |
| All other API calls | Session cookie + `businessId` | Authenticated session and `businessId` UUID parameter |

## HTTP Error Reference

When an API call fails due to an authentication or authorization problem, Tavryn returns one of the following status codes.

**400 Bad Request** `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.

**401 Unauthorized** `object`

No valid session or `Authorization` header was found. Sign in at `/auth` or supply the correct `CRON_SECRET`.

**403 Forbidden** `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.

**429 Too Many Requests** `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.

**500 Internal Server Error** `object`

An unexpected server-side error occurred. Retry with exponential backoff; if the problem persists, contact support.

> [!WARNING]
>
> 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**

```json theme={null}
{
  "success": false,
  "error": "Rate limit exceeded",
  "details": {
    "resetMs": 43200
  }
}
```

## Sign-In Methods

Tavryn supports the following sign-in methods:

> [card] 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.

> [card] OAuth (Google / GitHub)
>
> Authenticate with your existing Google or GitHub account. After completing OAuth consent you are redirected back to the Tavryn dashboard automatically.

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.