Skip to main content
bun add @ave-id/sdk
The SDK is split into focused pages. Start with the surface you need:

Quick Ave

startQuickSignIn, handleQuickCallback, getQuickIdentity.

OAuth and PKCE

buildAuthorizeUrl, exchangeCode, refreshToken, startPkceLogin, server helpers.

Ave Session

AveSession, storage adapters, Convex helpers, Svelte helpers, refresh coordination.

Connector

buildConnectorUrl, exchangeDelegatedToken, startConnectorFlow, delegation management.

Business workspaces

organizationId, org-context tokens, workspace picker and creation helpers.

Signing

createSignatureRequest, getSignatureStatus, verifySignature, openSigningPopup.

Identity keys

getIdentityKey, encryptPayloadForHandle, decryptWrappedPayload, URL-safe payload params.

​
Quick Ave

No dashboard. No client IDs. No environment variables. No redirect configuration. Protect a page: 
import { getQuickIdentity, startQuickSignIn } from "@ave-id/sdk/client";

const user = getQuickIdentity();
if (!user) await startQuickSignIn();
Callback route — create a page at /ave/callback that does exactly one thing: 
import { handleQuickCallback } from "@ave-id/sdk/client";

await handleQuickCallback();
That’s it. Quick Ave derives a client ID from your origin, handles PKCE, stores the token locally, and redirects back to where the user was. Nothing to register.
Evaluating whether this is easier than Clerk or Auth0? It is — because there’s no dashboard step at all. Ship a working prototype in under 2 minutes, then upgrade to the full OIDC flow when you’re ready for refresh tokens, app branding, or confidential flows.

​
startQuickSignIn(options?)

Generates PKCE parameters, saves the return-to URL, and redirects the user to Ave. 
async function startQuickSignIn(options?: {
  issuer?: string;       // default: "https://aveid.net"
  scope?: string;        // default: "openid profile email"
  redirectUri?: string;  // default: <origin>/ave/callback
  returnTo?: string;     // default: current URL
}): Promise<void>

​
handleQuickCallback(options?)

Convenience wrapper: calls finishQuickSignIn, then redirects the user to where they were before startQuickSignIn was called. 
async function handleQuickCallback(options?: {
  issuer?: string;
  redirectUri?: string;  // must match the redirectUri used in startQuickSignIn
  fallbackPath?: string; // where to go if no return-to is stored (default: "/")
}): Promise<QuickIdentity | null>

​
finishQuickSignIn(options?)

Exchanges the authorization code that Ave appended to your callback URL. Returns null when no code param is present — safe to call on every page load. 
async function finishQuickSignIn(options?: {
  issuer?: string;
  redirectUri?: string;
  url?: string;          // override URL to parse (default: window.location.href)
}): Promise<QuickIdentity | null>

​
getQuickIdentity(storageKey?)

Returns the cached QuickIdentity from localStorage, or null when not signed in or the token has expired locally. Makes no network request. 
function getQuickIdentity(storageKey?: string): QuickIdentity | null

​
clearQuickIdentity(storageKey?)

Removes the stored QuickIdentity (sign-out). 
function clearQuickIdentity(storageKey?: string): void

​
checkQuickSession(options?)

Validates the current token against the Ave server. Use this when you need a real-time check rather than relying on the local expiry. 
async function checkQuickSession(options?: {
  issuer?: string;
  storageKey?: string;
  token?: string;  // supply a token directly instead of reading from storage
}): Promise<{
  status: "active" | "login_required" | "unsupported";
  reason?: string;
}>

​
startQuickSessionMonitor(options?)

Starts a periodic checkQuickSession loop. Fires onLoginRequired and stops itself when the session is no longer valid. 
function startQuickSessionMonitor(options?: {
  issuer?: string;
  storageKey?: string;
  intervalMs?: number;  // default: 60 000
  onLoginRequired?: (result: { reason?: string }) => void;
  onError?: (error: Error) => void;
}): { stop: () => void }

​
QuickIdentity

interface QuickIdentity {
  userId: string;        // Ave identity UUID
  handle?: string;       // @handle
  displayName?: string;
  email?: string;
  avatarUrl?: string;
  /**
   * JWT access token (`access_token_jwt`) for Ave APIs.
   * Its audience is Ave's resource audience, not your app. Use `idToken` or
   * your own session for app API authentication.
   * Always verify server-side: check `iss`, `aud`, `exp`, and the JWT signature
   * against the JWKS endpoint before trusting claims.
   * The JWT payload always contains `quick: true` — Standard-only API
   * middleware can check for the absence of this claim to reject Quick tokens.
   * Upgrade to Standard Ave for confidential flows.
   */
  token: string;
  /**
   * OIDC id_token — pass this to Convex (`convex.setAuth`) or any service
   * that validates OIDC identity. Only present when `openid` scope was
   * requested (the default). `aud` equals your Quick Ave clientId:
   * `"origin:https://yourapp.com"`.
   */
  idToken?: string;
  expiresIn: number;     // seconds until expiry
  receivedAt: number;    // Unix ms when the token was stored
}
For a full walkthrough including Convex wiring, session monitoring, and the upgrade path see the Quick Ave guide.
Last modified on May 23, 2026