Skip to main content
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.
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 by replacing the Quick Ave calls with startPkceLogin / exchangeCode from the full SDK. No server changes required.

​
How it works

If you want Quick Ave to feel native to your app instead of a redirect-first flow, open it with the embed package: 
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.
1

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.
2

User authenticates

The user logs in (or confirms their existing Ave session). Ave issues a short-lived authorization code.
3

Ave redirects back

The user is redirected to https://yourapp.com/ave/callback?code=…&state=….
4

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.
5

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.
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

bun add @ave-id/sdk

​
Drop-in usage

1

Protect a page

Add this to any page that requires authentication:
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);
2

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:
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:
// React example
import { useEffect } from "react";
import { handleQuickCallback } from "@ave-id/sdk/client";

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

Sign out

import { clearQuickIdentity } from "@ave-id/sdk/client";

clearQuickIdentity();
// Optionally redirect to the homepage
window.location.href = "/";

​
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. 
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). 
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
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.

​
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".

Full Convex integration guide

Exact config, wiring, token details, and Convex function examples for both Quick Ave and registered apps.

​
Session monitoring

Start a background check so your app reacts immediately when a token is revoked or the session ends: 
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: 
// 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?

Upgrading to the standard OIDC flow

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.

​
Full API reference

See Quick Ave functions in the SDK reference.
Last modified on May 23, 2026