# Bring Your Own Auth (Pre-Authenticated Sessions)

Sign users into your AVCodex app from your own backend, with server-side identity that works across devices and inside iframe embeds.

---

If your application already authenticates its users (Entra ID, Okta, Auth0, WorkOS, Clerk, a custom SSO, or your own signed links), you do not need to make them sign in again inside AVCodex. Your backend can mint an AVCodex session for a user it has already verified, and the chat opens pre-authenticated: no login screen, no OTP, no second password.

This is the recommended pattern for white-label deployments, portals behind your own login, and governed workflows.

> **Note:** Because the consumer identity created this way lives on AVCodex servers, keyed by email, it is portable across devices. Any device where your backend mints a token for the same email is the same consumer, with the same conversation history.

## How it works

```
User opens your app or your protected link
    1. Your backend verifies the user (your auth, your signature checks)
    2. Your backend calls POST /api/v1/apps/{appId}/consumers/auth
       -> AVCodex finds or creates the consumer and returns a bearer token
    3. Your page passes the token to the embedded chat
       -> the user is signed in, no AVCodex login screen
```

AVCodex never sees or validates your credentials or signed links. Your backend is the authority: it decides who gets a token, and AVCodex trusts the Builder API call because it carries your secret API key.

## Step 1: Mint a token on your server

Call the Builder API endpoint `POST /api/v1/apps/{appId}/consumers/auth` from your backend. It requires a Builder API key with `consumers:write` scope.

```bash
curl -X POST https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/consumers/auth \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@integrator.com",
    "name": "Jane Doe",
    "metadata": { "accountTier": "enterprise", "siteId": "BLDG-4821" }
  }'
```

Response:

```json
{
  "data": {
    "token": "eyJhbGciOi...",
    "consumer": { "id": "...", "email": "jane@integrator.com", "name": "Jane Doe" },
    "expires_at": "2026-08-16T10:00:00Z"
  }
}
```

## Step 2: Pass the token to the chat

Hand the returned token to the embedded chat on page load. The consumer is signed in immediately, with their history intact.

## Security notes

- **Mint tokens server-side only.** The Builder API key must never reach the browser. If it does, anyone can mint a session for any email.
- **Verify before you mint.** AVCodex trusts your API call completely. Whatever email you pass becomes the authenticated identity. Check your own session first.
- **Tokens expire.** Mint fresh on each page load rather than caching long-lived tokens client-side.

## Why this matters for AV deployments

Most enterprise AV clients will not accept a second login for a room-support tool. If the user is already signed into the corporate intranet or the facilities portal, the support agent has to inherit that session or adoption dies at the login screen.

This is also how you attach room and site context without asking the user. Pass `siteId`, `buildingId`, or `roomId` in `metadata` at token mint time, and the agent knows where the user is before the first message.

*AVCodex · Your AV expertise. Amplified by AI.*