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

# @ave-id/sdk

> Typed helpers for Quick Ave, OAuth, Connector delegation, Signing, and framework session integrations.

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

The SDK is split into focused pages. Start with the surface you need:

<CardGroup cols={3}>
  <Card title="Quick Ave" icon="bolt">
    `startQuickSignIn`, `handleQuickCallback`, `getQuickIdentity`.
  </Card>

  <Card title="OAuth and PKCE" icon="key" href="/sdk/sdk-oauth">
    `buildAuthorizeUrl`, `exchangeCode`, `refreshToken`, `startPkceLogin`, server helpers.
  </Card>

  <Card title="Ave Session" icon="rotate" href="/guides/ave-session-and-tokens">
    `AveSession`, storage adapters, Convex helpers, Svelte helpers, refresh coordination.
  </Card>

  <Card title="Connector" icon="link" href="/sdk/sdk-connector">
    `buildConnectorUrl`, `exchangeDelegatedToken`, `startConnectorFlow`, delegation management.
  </Card>

  <Card title="Business workspaces" icon="building" href="/guides/business-workspaces">
    `organizationId`, org-context tokens, workspace picker and creation helpers.
  </Card>

  <Card title="Signing" icon="pen-nib" href="/sdk/sdk-signing">
    `createSignatureRequest`, `getSignatureStatus`, `verifySignature`, `openSigningPopup`.
  </Card>

  <Card title="Identity keys" icon="lock" href="/sdk/sdk-identity-keys">
    `getIdentityKey`, `encryptPayloadForHandle`, `decryptWrappedPayload`, URL-safe payload params.
  </Card>
</CardGroup>

***

## Quick Ave

No dashboard. No client IDs. No environment variables. No redirect configuration.

**Protect a page**:

```ts theme={null}
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:

```ts theme={null}
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.

<Tip>
  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](/guides/quick-ave-to-standard) when you're ready for refresh tokens, app branding, or confidential flows.
</Tip>

### `startQuickSignIn(options?)`

Generates PKCE parameters, saves the return-to URL, and redirects the user to Ave.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
function getQuickIdentity(storageKey?: string): QuickIdentity | null
```

***

### `clearQuickIdentity(storageKey?)`

Removes the stored `QuickIdentity` (sign-out).

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
function startQuickSessionMonitor(options?: {
  issuer?: string;
  storageKey?: string;
  intervalMs?: number;  // default: 60 000
  onLoginRequired?: (result: { reason?: string }) => void;
  onError?: (error: Error) => void;
}): { stop: () => void }
```

***

### `QuickIdentity`

```ts theme={null}
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
}
```

<Note>
  For a full walkthrough including Convex wiring, session monitoring, and the upgrade path see the [Quick Ave guide](/guides/quick-ave).
</Note>