Skip to main content
OAuth tokens expire on a short clock. That is separate from how long a user should stay signed in. When your app requests offline_access, Ave issues a refresh token so your app can rotate tokens without sending the user through consent again. AveSession gives you one supported lifecycle for that work: persist the token bundle and any encryption keys, refresh before expiry, collapse duplicate refresh calls, broadcast changes across tabs, and save rotated refresh tokens atomically.

When to use it

  • You requested offline_access and want refresh handled for you.
  • You requested an encryption scope and want the keys kept next to the tokens.
  • You need a fresh id_token for Convex, your API, or another auth client.
  • You want to avoid duplicated refresh calls, stale refresh tokens, and cold-start races.
  • You need adapters for Convex, Svelte, or Expo.

Disconnected apps

Disconnecting an app in Ave invalidates its refresh tokens and access to Ave APIs for the selected identity, and deletes its encryption keys for that identity. Handle a definitive invalid_grant by clearing the app session and starting sign-in again. Reconnecting requires consent, does not reactivate old tokens, and provisions new encryption keys. An ID token already accepted by another service remains subject to that service’s session policy and the token’s expiry. Signing out locally only clears the local session.

Create a session

completeOAuthCallback runs finishPkceLogin and setTokensFromResponse together. Use it on your OAuth callback route, then call hydrate() during app startup. If the redirect carries encryption keys in its fragment, finishPkceLogin merges them into the token response and removes them from the URL. session.getAppKeyBase64(), getAppPublicKeyBase64(), and getAppPrivateKeyBase64() return the stored keys after hydrate().
Set devtools: true only in development. It exposes window.__aveSessionDev with state, expiry helpers, and lastRefreshError.
getValidIdToken() waits for proactive refresh when the JWT is near expiry. createLocalStorageAdapter() keeps the refresh token and any encryption keys in localStorage. For stricter setups, use createMemoryStorage(), your own AveSessionStorage, or a backend-for-frontend with customRefresh.

Convex

Call session.setTokensFromResponse after login. wireAveSessionToConvex passes a function that calls getValidIdToken() so Convex always receives a valid token.

Svelte

Hydrate in onMount before relying on authenticated UI.

Expo

Native Expo has no Web Crypto for PKCE SHA-256. Configure expo-crypto once with configureAveSdkForExpo from @ave-id/sdk/expo-session, then use AveSession with createSecureStoreAdapter and completeExpoOAuthCallback. See Expo with AuthSession.

Backend refresh

Pass customRefresh in AveSession options to POST to your own /api/session/refresh endpoint. That endpoint can read an HttpOnly cookie and return TokenResponse-shaped JSON. The client never stores the refresh token.

Encryption keys

When a sign-in requests e2ee:symmetric or e2ee:asymmetric, Ave appends the keys to the callback fragment. completeOAuthCallback, completeExpoOAuthCallback, and the embed’s onTokens merge them into the token response, and setTokensFromResponse stores them in the snapshot next to your tokens. Refreshes keep the stored keys. A sign-in with e2ee:reset replaces them, and the snapshot exposes the previous keys as appKeyBase64Old, appPublicKeyBase64Old, and appPrivateKeyBase64Old with appEncryptionWasReset set so you can re-encrypt existing data. signOut() clears keys along with tokens. AveSession stores keys wherever its storage adapter stores tokens. Choose the adapter with that in mind, and import keys with Web Crypto as shown in End-to-end encryption. setAppKeyBase64() replaces or clears the symmetric key if you manage it yourself.

Dev tools

With devtools: true, window.__aveSessionDev exposes getState(), expiry helpers, and lastRefreshError in development builds.

Server APIs

Send await session.getValidIdToken() as a bearer token to your backend. On the server, verifyAveIdTokenFromAuthHeader from @ave-id/sdk/server verifies the signature, issuer, audience, and expiry, and returns the identity ID as subject:
Use verifyAveIdToken(token, { clientId }) when the token comes from somewhere other than an Authorization header.
Last modified on September 28, 2026