Quickstart

This guide builds a browser app that signs users in with Ave and receives an AES-256 key for encrypting their data on the client. It takes a registered app, one scope, and two SDK calls.

Register your app

Create the app

Go to devs.aveid.net and create an app. You get a client ID, which is safe to ship in browser code, and a client secret, which only belongs on a server. Browser and mobile apps use PKCE and never need the secret.

Add the exact URL Ave should return users to, such as https://yourapp.com/callback. It must match character for character, including any trailing slash.Turn on development mode to allow localhost, loopback, and Expo Go callbacks on any port while you build. Production callbacks must still be listed explicitly.

Choose the encryption mode

Encryption is requested per sign-in with a scope, so there is nothing else to configure in the portal:

Scope	You receive
`e2ee:symmetric`	One AES-256 key per user for your app
`e2ee:asymmetric`	A P-256 keypair per user, and lookup of other users’ public keys

This guide uses e2ee:symmetric. See End-to-end encryption for the asymmetric mode.

Install the SDK

bun add @ave-id/sdk

Redirect
Embed

Start sign-in from a button. startPkceLogin generates the PKCE verifier, state, and nonce, stores them in sessionStorage, and redirects to Ave.

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

await startPkceLogin({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  scope: "openid profile offline_access e2ee:symmetric",
});

On the callback page, completeOAuthCallback checks state, exchanges the code, verifies the returned JWTs, reads the key from the URL fragment, removes it from the address bar, and saves everything in an AveSession.

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",
};

export const session = new AveSession({
  oauth,
  storage: createLocalStorageAdapter(),
});

await completeOAuthCallback(session, oauth);

const appKeyBase64 = session.getAppKeyBase64();

On later page loads, call await session.hydrate() before reading tokens or the key.

@ave-id/embed opens Ave in a sheet over your page and handles PKCE, state, nonce, and the code exchange. The key arrives in onTokens alongside the tokens.

bun add @ave-id/embed

import { startAveAuth } from "@ave-id/embed";
import { AveSession, createLocalStorageAdapter } from "@ave-id/sdk";

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

await startAveAuth({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  scope: "openid profile offline_access e2ee:symmetric",
  onTokens: async (tokens) => {
    await session.setTokensFromResponse(tokens);
  },
  onError: ({ message }) => showError(message),
});

Call startAveAuth from a click handler so the browser allows a popup if Ave needs one.

The key is delivered in the callback URL fragment (#app_key=...). Browsers never send fragments to servers, so the key does not pass through Ave’s token endpoint or your backend.

createLocalStorageAdapter() keeps tokens and the key in localStorage, where any script on your origin can read them. It is the simplest option; Ave Session covers memory-only and custom storage.

Encrypt data on the client

Import the key into Web Crypto and use AES-GCM with a fresh 12-byte IV for every message.

const keyBytes = Uint8Array.from(atob(appKeyBase64!), (c) => c.charCodeAt(0));
const key = await crypto.subtle.importKey("raw", keyBytes, "AES-GCM", false, ["encrypt", "decrypt"]);

const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = await crypto.subtle.encrypt(
  { name: "AES-GCM", iv },
  key,
  new TextEncoder().encode("private note"),
);

Store the IV next to the ciphertext. Your backend only ever sees these two values. The same user receives the same key every time they sign in to your app, on any device where their Ave account is unlocked. A different identity receives a different key.

Authenticate API requests

Send the id_token to your backend and verify it there. Its audience is your client ID, and sub is the stable identity ID to key rows by.

// Browser
const idToken = await session.getValidIdToken();
await fetch("/api/notes", {
  method: "POST",
  headers: { Authorization: `Bearer ${idToken}` },
  body: JSON.stringify({ iv: toBase64(iv), ciphertext: toBase64(ciphertext) }),
});

// Server
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 });

await saveNote({ ownerId: principal.subject, iv, ciphertext });

getValidIdToken() refreshes tokens before they expire when you requested offline_access, and saves the rotated refresh token.

Errors

invalid_client

The client ID or client secret does not match a registered app.

invalid_grant

The authorization code or refresh token is invalid, expired, or already used. Codes are single-use and short-lived, so exchange them as soon as the callback loads.

invalid_request

A required field is missing, most often the PKCE verifier.

invalid_scope

A standard scope is not in your app’s allowlist, or the request asked for more than one encryption mode.

Next steps

End-to-end encryption

Asymmetric keys, encrypting for other users, and key rotation.

Encryption model

How keys are wrapped, unlocked, and delivered.

Ave Session

Storage choices, refresh, and framework adapters.

OAuth details

Token payloads, manual PKCE, and validation steps.

Overview

Core concepts

Quickstart

Register your app

Install the SDK

Encrypt data on the client

Authenticate API requests

Errors

Next steps

End-to-end encryption

Encryption model

Ave Session

OAuth details

​Register your app

​Install the SDK

​Sign in and receive the key

​Encrypt data on the client

​Authenticate API requests

​Errors

​Next steps

End-to-end encryption

Encryption model

Ave Session

OAuth details

Register your app

Install the SDK

Sign in and receive the key

Encrypt data on the client

Authenticate API requests

Errors

Next steps