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

# Quick Ave

> Add Ave authentication to any site in minutes — no app registration, no client secret, no redirect-URI configuration. Uses PKCE under the hood and is fully upgradeable to the standard OIDC flow.

Quick Ave is a zero-configuration authentication layer. The SDK derives a `clientId` from your site's origin (`origin:https://yourapp.com`), generates PKCE parameters automatically, and handles everything from the initial redirect through to the token exchange and session monitoring. You don't register an app in the developer portal.

<Note>
  Quick Ave is designed for rapid prototyping and internal tooling. When you are ready to go to production — or need features like refresh tokens, app branding on the consent screen, E2EE, or the Connector flow — upgrade to the [standard OIDC flow](/quickstart) by replacing the Quick Ave calls with `startPkceLogin` / `exchangeCode` from the full SDK. No server changes required.
</Note>

## How it works

## Recommended UX

If you want Quick Ave to feel native to your app instead of a redirect-first flow, open it with the embed package:

```ts theme={null}
import { startAveAuth } from "@ave-id/embed";

startAveAuth({
  redirectUri: "https://yourapp.com/ave/callback",
  onSuccess: ({ redirectUrl }) => {
    window.location.assign(redirectUrl);
  },
});
```

That keeps the user on your page first, opens a popup only when the browser requires it, and still lands on the same callback route.

<Steps>
  <Step title="Initiate sign-in">
    Your page calls `startQuickSignIn()`. The SDK saves a PKCE verifier and a `state` nonce in `sessionStorage`, then redirects the user to `aveid.net/signin` with `client_id=origin:https://yourapp.com`.
  </Step>

  <Step title="User authenticates">
    The user logs in (or confirms their existing Ave session). Ave issues a short-lived authorization code.
  </Step>

  <Step title="Ave redirects back">
    The user is redirected to `https://yourapp.com/ave/callback?code=…&state=…`.
  </Step>

  <Step title="Exchange the code">
    Your callback page calls `handleQuickCallback()`. The SDK verifies the state, exchanges the code for a 1-hour access token, stores the identity in `localStorage`, and redirects the user back to where they were.
  </Step>

  <Step title="Read the identity on every page load">
    Your app calls `getQuickIdentity()`. A background session monitor can call `clearQuickIdentity()` and prompt the user to re-authenticate when the token expires.
  </Step>
</Steps>

**Security model:** PKCE (S256) is the only authentication mechanism. There is no client secret. The server validates that the `redirect_uri` origin matches the `clientId` origin at both authorize time and token-exchange time, so a malicious site cannot impersonate your `clientId`. An HTTP `Origin` header mismatch during token exchange is also rejected. Tokens include a `quick: true` JWT claim so Standard-only API middleware can detect and reject them. Tokens are scoped to `openid profile email` and expire after one hour. Refresh tokens are not issued.

***

## Install

```bash theme={null}
bun add @ave-id/sdk
```

***

## Drop-in usage

<Steps>
  <Step title="Protect a page">
    Add this to any page that requires authentication:

    ```ts theme={null}
    import { getQuickIdentity, startQuickSignIn } from "@ave-id/sdk/client";

    const user = getQuickIdentity();

    if (!user) {
      // Redirects to Ave. When the user comes back, handleQuickCallback()
      // on your callback page will send them straight back here.
      await startQuickSignIn();
    }

    // user is now a QuickIdentity
    console.log(user.displayName, user.email);
    ```
  </Step>

  <Step title="Add a callback page at /ave/callback">
    Create a page at exactly that path (the default). Its only job is to finish the sign-in:

    ```ts theme={null}
    import { handleQuickCallback } from "@ave-id/sdk/client";

    // Call once on page load — exchanges the code, stores the identity,
    // and redirects back to where the user came from.
    await handleQuickCallback();
    ```

    In a **SPA** (React, Svelte, Vue …) add a route for `/ave/callback` that calls `handleQuickCallback()` on mount:

    ```tsx theme={null}
    // React example
    import { useEffect } from "react";
    import { handleQuickCallback } from "@ave-id/sdk/client";

    export default function AveCallback() {
      useEffect(() => { handleQuickCallback(); }, []);
      return <p>Signing in…</p>;
    }
    ```
  </Step>

  <Step title="Sign out">
    ```ts theme={null}
    import { clearQuickIdentity } from "@ave-id/sdk/client";

    clearQuickIdentity();
    // Optionally redirect to the homepage
    window.location.href = "/";
    ```
  </Step>
</Steps>

***

## Reading the identity

`getQuickIdentity()` returns `null` when the user is not signed in or the local token has expired. It never makes a network request.

```ts theme={null}
const user = getQuickIdentity();

if (user) {
  console.log(user.userId);      // Ave identity UUID
  console.log(user.handle);      // @handle
  console.log(user.displayName); // display name
  console.log(user.email);       // email (if granted)
  console.log(user.avatarUrl);   // avatar URL (if set)
  console.log(user.token);       // JWT access token for Ave APIs (contains quick: true)
  console.log(user.idToken);     // OIDC id_token — use with Convex and other OIDC-aware services
}
```

***

## Calling your own API

Use `idToken` when your own API needs to know who signed in. It is the OIDC identity token and its audience is your Quick Ave client ID (`origin:https://yourapp.com`).

```ts theme={null}
const user = getQuickIdentity();

const res = await fetch("/api/me", {
  headers: { Authorization: `Bearer ${user!.idToken}` },
});
```

On your server, verify the JWT:

* `iss`: `https://aveid.net`
* `aud`: `origin:https://yourapp.com`
* `sub`: the user's Ave identity UUID
* JWKS endpoint: `https://aveid.net/.well-known/jwks.json`

<Note>
  `user.token` is the Ave API access JWT (`access_token_jwt`) with `aud: "https://aveid.net"`. Do not accept it as a generic login token for your API. Use `user.idToken`, or create your own app session after verifying it.
</Note>

***

## Using with Convex

The `idToken` field on `QuickIdentity` is the OIDC `id_token` — pass it to `ConvexProviderWithAuth` for authenticated Convex queries. Your `auth.config.ts` `applicationID` should be `"origin:https://yourapp.com"`.

<Card title="Full Convex integration guide" icon="database" href="/guides/convex-custom-auth">
  Exact config, wiring, token details, and Convex function examples for both Quick Ave and registered apps.
</Card>

***

## Session monitoring

Start a background check so your app reacts immediately when a token is revoked or the session ends:

```ts theme={null}
import { startQuickSessionMonitor, clearQuickIdentity, startQuickSignIn } from "@ave-id/sdk/client";

const monitor = startQuickSessionMonitor({
  intervalMs: 60_000, // check every minute (default)
  onLoginRequired({ reason }) {
    clearQuickIdentity();
    startQuickSignIn(); // re-authenticate
  },
  onError(err) {
    console.warn("Session check failed:", err);
  },
});

// Stop the monitor when your component unmounts
// monitor.stop();
```

***

## Custom callback path

If you can't use `/ave/callback`, pass the same `redirectUri` to both `startQuickSignIn` and `handleQuickCallback`:

```ts theme={null}
// Initiating sign-in
await startQuickSignIn({ redirectUri: "https://yourapp.com/auth/callback" });

// On your /auth/callback page
await handleQuickCallback({
  redirectUri: "https://yourapp.com/auth/callback",
  fallbackPath: "/dashboard",
});
```

***

## Ready to go beyond Quick Ave?

<Card title="Upgrading to the standard OIDC flow" icon="arrow-right" href="/guides/quick-ave-to-standard">
  Step-by-step guide to swapping Quick Ave for a registered app. Get refresh tokens, app branding, E2EE, and Connector access. The token format doesn't change — only the function calls.
</Card>

***

## Full API reference

See [Quick Ave functions in the SDK reference](/sdk/javascript-sdk).