@ave-id/sdk OAuth

These functions take the client ID of an app registered at devs.aveid.net. New to Ave? Start with the quickstart.

bun add @ave-id/sdk

Import paths

Import	Contents	Runtime
`@ave-id/sdk`	PKCE helpers, `buildAuthorizeUrl`, `exchangeCode`, `refreshToken`, `fetchUserInfo`, `verifyJwt`, `fetchJwks`	Any
`@ave-id/sdk/client`	`startPkceLogin`, `finishPkceLogin`, `completeOAuthCallback`	Browser
`@ave-id/sdk/server`	`verifyAveIdToken`, `verifyAveIdTokenFromAuthHeader`, `exchangeCodeServer`, `refreshTokenServer`	Server
`@ave-id/sdk/expo-session`	`configureAveSdkForExpo`, `completeExpoOAuthCallback`, `AveSession`, SecureStore adapter	Expo

See @ave-id/sdk for every import path.

Never use exchangeCodeServer or refreshTokenServer in browser code. They require your clientSecret, which must never be exposed to the client.

Config object

Most functions take a config object as the first argument:

interface AveConfig {
  clientId: string;     // Your app's client ID
  redirectUri: string;  // Registered redirect URI
  issuer?: string;      // Base URL for Ave user-facing pages (default: "https://aveid.net"). Do not set this to the API host "https://api.aveid.net".
}

PKCE helpers

`generateCodeVerifier()`

Generates a cryptographically random PKCE code verifier.

function generateCodeVerifier(): string

Returns a 43-character base64url-encoded random string. Store this in sessionStorage before redirecting and send it as codeVerifier when exchanging the code.

const verifier = generateCodeVerifier();
sessionStorage.setItem("ave_verifier", verifier);

`generateCodeChallenge(verifier)`

Generates the PKCE code challenge from a verifier using SHA-256.

function generateCodeChallenge(verifier: string): Promise<string>

string

required

The code verifier from generateCodeVerifier().

Returns Promise<string> — the base64url-encoded SHA-256 hash. Pass this as codeChallenge to buildAuthorizeUrl.

const challenge = await generateCodeChallenge(verifier);

`generateNonce()`

Generates a random nonce for ID token replay protection.

function generateNonce(): string

Returns a 32-character base64url-encoded random string. Pass it as nonce to buildAuthorizeUrl and verify it matches the nonce claim in the id_token after exchange.

Authorization functions

`buildAuthorizeUrl(config, params)`

Builds the URL to redirect users to Ave for sign-in.

function buildAuthorizeUrl(
  config: AveConfig,
  params?: {
    scope?: string[];
    state?: string;
    nonce?: string;
    codeChallenge?: string;
    codeChallengeMethod?: "S256" | "plain";
    prompt?: OAuthPrompt | OAuthPrompt[] | string;
    extraParams?: Record<string, string>;
  }
): string

string

required

Your app’s client ID.

string

required

The registered redirect URI the user will be sent to after authorization.

string[]

default:"[\"openid\", \"profile\", \"email\"]"

Scopes to request: "openid", "profile", "email", "offline_access", "user_id", and one of "e2ee:symmetric" or "e2ee:asymmetric", optionally with "e2ee:reset". See Scopes and claims.

string

CSRF protection token. Generate with crypto.randomUUID(). Store and verify on the callback.

string

ID token replay protection. Generate with generateNonce(). Verify against the nonce claim in id_token.

string

PKCE challenge from generateCodeChallenge(). Required for public clients.

"none" | "login" | "consent" | "select_account" | string

OAuth-style interaction hint. Use select_account when your app offers Switch account or Sign out so Ave always shows the swipe-to-authorize screen and identity picker instead of silently reusing the last authorization. Combine values with a space (for example consent select_account).

object

Extra query parameters on the Ave sign-in URL. Encryption is requested with scopes, not extra parameters; see App encryption.

const url = buildAuthorizeUrl(
  { clientId: "YOUR_CLIENT_ID", redirectUri: "https://yourapp.com/callback" },
  {
    scope: ["openid", "profile", "email", "offline_access"],
    state: crypto.randomUUID(),
    nonce: generateNonce(),
    codeChallenge: challenge,
    codeChallengeMethod: "S256",
  }
);
window.location.href = url;

`buildSwitchAccountUrl(config, params?)`

Convenience wrapper around buildAuthorizeUrl that sets prompt=select_account. Use from your app’s Switch account or Use a different profile action so Ave skips instant re-authorization and always shows the identity picker plus swipe-to-authorize UI.

function buildSwitchAccountUrl(
  config: AveConfig,
  params?: Parameters<typeof buildAuthorizeUrl>[1]
): string

import { buildSwitchAccountUrl, generateCodeChallenge, generateCodeVerifier, generateNonce } from "@ave-id/sdk";

const verifier = generateCodeVerifier();
const challenge = await generateCodeChallenge(verifier);

window.location.href = buildSwitchAccountUrl(
  { clientId: "YOUR_CLIENT_ID", redirectUri: "https://yourapp.com/callback" },
  {
    scope: ["openid", "profile", "email", "offline_access"],
    state: crypto.randomUUID(),
    nonce: generateNonce(),
    codeChallenge: challenge,
    codeChallengeMethod: "S256",
  }
);

For embed flows, pass extraParams: { prompt: "select_account" } to openAveSheet / openAvePopup instead.

`exchangeCode(config, payload)`

Exchanges an authorization code for tokens. Use for PKCE (public client) flows.

function exchangeCode(
  config: AveConfig,
  payload: { code: string; codeVerifier?: string }
): Promise<TokenResponse>

string

required

The authorization code from the callback URL.

string

The PKCE code verifier from sessionStorage. Required if you used PKCE.

const tokens = await exchangeCode(
  { clientId: "YOUR_CLIENT_ID", redirectUri: "https://yourapp.com/callback" },
  { code, codeVerifier }
);

`refreshToken(config, payload)`

Exchanges a refresh token for a new set of tokens.

function refreshToken(
  config: AveConfig,
  payload: { refreshToken: string }
): Promise<TokenResponse>

string

required

The refresh token from a previous token response.

Refresh tokens rotate on every use — each successful refresh returns a new refresh token and invalidates the old one. Store the new token immediately after every refresh. Sending an old token returns invalid_grant and may revoke the entire token family.

`fetchUserInfo(config, accessToken)`

Fetches live identity claims from the userinfo endpoint.

function fetchUserInfo(config: AveConfig, accessToken: string): Promise<UserInfo>

string

required

The opaque access_token (not the JWT) from the token response.

Returns UserInfo with sub, name?, preferred_username?, email?, picture?.

Client helpers

Import from @ave-id/sdk/client. Browser-only.

`startPkceLogin(params)`

Generates PKCE params, saves them to sessionStorage, and redirects the user to Ave. The browser-friendly alternative to calling generateCodeVerifier + buildAuthorizeUrl + window.location.href manually.

async function startPkceLogin(params: {
  clientId: string;
  redirectUri: string;
  scope?: string;
  issuer?: string;
  state?: string;   // optional — auto-generated if omitted
  nonce?: string;   // optional — auto-generated if omitted
  prompt?: "none" | "login" | "consent" | "select_account" | string;
}): Promise<void>

Automatically generates a PKCE verifier/challenge, a nonce for ID token replay protection, and a state value for CSRF protection — unless you supply your own. All three are stored in sessionStorage and retrieved automatically by finishPkceLogin.

`finishPkceLogin(options)`

Handles the OAuth callback: reads stored PKCE state, verifies the returned state against the stored value, exchanges the authorization code, merges encryption keys from the URL fragment, verifies the returned tokens, removes keys from the address bar, and cleans up sessionStorage. Returns null when no code parameter is present — safe to call on every page load.

async function finishPkceLogin(options: {
  clientId: string;
  redirectUri: string;
  issuer?: string;
  url?: string;        // override the callback URL to parse (default: window.location.href)
  cleanUrl?: boolean;  // remove code/state from the URL after exchange (default: true)
}): Promise<TokenResponse | null>

import { startPkceLogin, finishPkceLogin } from "@ave-id/sdk/client";

// On your login page:
await startPkceLogin({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  scope: "openid profile email offline_access",
});

// On your /callback page:
const tokens = await finishPkceLogin({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
});

if (tokens) {
  // User is signed in — tokens.id_token, tokens.app_key, etc.
}

`completeOAuthCallback(session, options)`

Runs finishPkceLogin with the same options, then saves the tokens and any encryption keys with session.setTokensFromResponse. Returns the token response, or null when the URL has no code.

async function completeOAuthCallback(
  session: AveSession,
  options: Parameters<typeof finishPkceLogin>[0],
): Promise<TokenResponse | null>

import { AveSession, createLocalStorageAdapter } from "@ave-id/sdk";
import { completeOAuthCallback } from "@ave-id/sdk/client";

const oauth = { clientId: "YOUR_CLIENT_ID", redirectUri: "https://yourapp.com/callback" };
const session = new AveSession({ oauth, storage: createLocalStorageAdapter() });

await completeOAuthCallback(session, oauth);
session.getAppKeyBase64();

JWT verification

These functions are available in @ave-id/sdk, @ave-id/sdk/client, and @ave-id/sdk/server.

`verifyJwt(token, options?)`

Verifies an Ave-issued JWT: parses the token, fetches the OIDC discovery document, validates the RS256 signature against the JWKS, and checks issuer, expiry, audience, and nonce claims. Returns the decoded payload on success or null on any validation failure.

async function verifyJwt<T extends JwtPayload = AveJwtClaims>(
  token: string,
  options?: VerifyJwtOptions,
): Promise<T | null>

interface VerifyJwtOptions {
  issuer?: string;             // Base issuer URL (default: "https://aveid.net")
  expectedIssuer?: string;     // Exact issuer string to validate iss claim against
  audience?: string | string[]; // Expected aud claim (e.g. your clientId)
  nonce?: string;              // Expected nonce claim (replay protection)
  jwksUrl?: string;            // Override JWKS endpoint URL
  jwks?: JwksResponse;         // Pre-fetched JWKS (skips network call)
  discoveryUrl?: string;       // Override OIDC discovery endpoint
  clockSkewSeconds?: number;   // Clock tolerance for exp/iat checks (default: 30)
  fetcher?: typeof fetch;      // Custom fetch implementation
}

string

required

The raw JWT string to verify.

string | string[]

Expected aud claim. Pass your clientId when verifying id_token. Pass "https://aveid.net" when verifying access_token_jwt.

string

Expected nonce claim. Pass the nonce you sent in the authorization request to prevent replay attacks.

number

default:"30"

Tolerance in seconds applied to exp and nbf checks to handle clock drift between servers.

Returns Promise<T | null> — the decoded payload typed as T, or null if any check fails (invalid signature, expired, issuer mismatch, audience mismatch, nonce mismatch, or malformed token).

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

// Verify an id_token on your server after code exchange:
const claims = await verifyJwt(tokens.id_token, {
  audience: "YOUR_CLIENT_ID",
  nonce: savedNonce,
});

if (!claims) {
  throw new Error("Invalid id_token");
}

// claims.sub — identity UUID
// claims.email, claims.name, etc.

verifyJwt fetches the OIDC discovery document and JWKS automatically and caches both for 5 minutes. For server environments with no global fetch, pass a fetcher option.

`fetchJwks(options?)`

Fetches and caches the Ave JWKS (JSON Web Key Set). Used internally by verifyJwt. Useful if you need direct access to the signing keys.

async function fetchJwks(options?: {
  issuer?: string;
  jwksUrl?: string;
  fetcher?: typeof fetch;
}): Promise<JwksResponse>

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

const { keys } = await fetchJwks();
// keys: JwkKey[] — RSA public keys used to verify Ave JWTs

Server helpers

Import from @ave-id/sdk/server.

`verifyAveIdToken(token, options)`

Verifies an Ave id_token for your client ID: signature, issuer, audience, and expiry. Returns the claims, or null.

async function verifyAveIdToken(
  token: string,
  options: { clientId: string; issuer?: string; fetcher?: typeof fetch },
): Promise<AveIdTokenClaims | null>

`verifyAveIdTokenFromAuthHeader(authorization, options)`

Reads a Bearer token from an Authorization header value and verifies it with verifyAveIdToken. Returns { subject, claims }, where subject is the identity ID, or null.

import { verifyAveIdTokenFromAuthHeader } from "@ave-id/sdk/server";

const principal = await verifyAveIdTokenFromAuthHeader(request.headers.get("authorization"), {
  clientId: process.env.AVE_CLIENT_ID!,
});
if (!principal) return new Response("Unauthorized", { status: 401 });

getBearerToken(authorization) returns the raw token from a header value without verifying it.

`exchangeCodeServer(config, payload)`

Same as exchangeCode but uses clientSecret instead of codeVerifier. Use this for confidential clients (server-side token exchange).

async function exchangeCodeServer(
  config: { clientId: string; clientSecret: string; redirectUri: string; issuer?: string },
  payload: { code: string }
): Promise<TokenResponse>

import { exchangeCodeServer } from "@ave-id/sdk/server";

const tokens = await exchangeCodeServer(
  {
    clientId: process.env.AVE_CLIENT_ID!,
    clientSecret: process.env.AVE_CLIENT_SECRET!,
    redirectUri: "https://yourapp.com/callback",
  },
  { code }
);

`refreshTokenServer(config, payload)`

Refreshes tokens using client secret (confidential client).

async function refreshTokenServer(
  config: { clientId: string; clientSecret: string; redirectUri: string; issuer?: string },
  payload: { refreshToken: string }
): Promise<TokenResponse>

TokenResponse

The shape returned by exchangeCode, exchangeCodeServer, refreshToken, refreshTokenServer, and finishPkceLogin. The token endpoint never returns key fields; finishPkceLogin, completeOAuthCallback, and mergeAppEncryptionFromUrl add them from the callback fragment.

interface TokenResponse {
  access_token: string;      // Opaque bearer token for Ave API endpoints
  access_token_jwt: string;  // Signed Ave API JWT (aud: https://aveid.net)
  id_token?: string;         // OIDC JWT (aud: your clientId) — requires openid scope
  refresh_token?: string;    // Rotation token — requires offline_access scope
  token_type: "Bearer";
  expires_in: number;        // Seconds until access_token expires
  scope: string;             // Space-separated granted scopes
  user_id?: string;          // Present when user_id scope is granted
  user?: {                   // May be absent depending on scopes/config
    id: string;
    handle?: string;
    displayName?: string;
    email?: string;
    avatarUrl?: string | null;
  } | null;
  app_key?: string;             // Merged from the callback fragment (e2ee:symmetric)
  app_public_key?: string;      // Merged from the callback fragment (e2ee:asymmetric)
  app_private_key?: string;     // Merged from the callback fragment (e2ee:asymmetric)
  app_key_old?: string;         // Previous keys after e2ee:reset
  app_public_key_old?: string;
  app_private_key_old?: string;
  app_key_reset?: boolean;
}

Error handling

All SDK functions throw an Error when the server returns a non-2xx response. The error message is the error field from the response body (e.g. "invalid_grant", "invalid_client").

try {
  const tokens = await exchangeCode(config, { code, codeVerifier });
} catch (err) {
  if (err.message === "invalid_grant") {
    // Code expired or PKCE verifier mismatch
  }
}

JavaScript SDK

Embed SDK

@ave-id/sdk OAuth

Import paths

Config object

PKCE helpers

`generateCodeVerifier()`

`generateCodeChallenge(verifier)`

`generateNonce()`

Authorization functions

`buildAuthorizeUrl(config, params)`

`buildSwitchAccountUrl(config, params?)`

`exchangeCode(config, payload)`

`refreshToken(config, payload)`

`fetchUserInfo(config, accessToken)`

Client helpers

`startPkceLogin(params)`

`finishPkceLogin(options)`

`completeOAuthCallback(session, options)`

JWT verification

`verifyJwt(token, options?)`

`fetchJwks(options?)`

Server helpers

`verifyAveIdToken(token, options)`

`verifyAveIdTokenFromAuthHeader(authorization, options)`

`exchangeCodeServer(config, payload)`

`refreshTokenServer(config, payload)`

TokenResponse

Error handling

See also

​Import paths

​Config object

​PKCE helpers

​generateCodeVerifier()

​generateCodeChallenge(verifier)

​generateNonce()

​Authorization functions

​buildAuthorizeUrl(config, params)

​buildSwitchAccountUrl(config, params?)

​exchangeCode(config, payload)

​refreshToken(config, payload)

​fetchUserInfo(config, accessToken)

​Client helpers

​startPkceLogin(params)

​finishPkceLogin(options)

​completeOAuthCallback(session, options)

​JWT verification

​verifyJwt(token, options?)

​fetchJwks(options?)

​Server helpers

​verifyAveIdToken(token, options)

​verifyAveIdTokenFromAuthHeader(authorization, options)

​exchangeCodeServer(config, payload)

​refreshTokenServer(config, payload)

​TokenResponse

​Error handling

​See also

Import paths

Config object

PKCE helpers

`generateCodeVerifier()`

`generateCodeChallenge(verifier)`

`generateNonce()`

Authorization functions

`buildAuthorizeUrl(config, params)`

`buildSwitchAccountUrl(config, params?)`

`exchangeCode(config, payload)`

`refreshToken(config, payload)`

`fetchUserInfo(config, accessToken)`

Client helpers

`startPkceLogin(params)`

`finishPkceLogin(options)`

`completeOAuthCallback(session, options)`

JWT verification

`verifyJwt(token, options?)`

`fetchJwks(options?)`

Server helpers

`verifyAveIdToken(token, options)`

`verifyAveIdTokenFromAuthHeader(authorization, options)`

`exchangeCodeServer(config, payload)`

`refreshTokenServer(config, payload)`

TokenResponse

Error handling

See also