OAuth authorization code flow

The authorization code flow is the standard way to authenticate users with Ave. The user is redirected to Ave, authenticates, and Ave redirects back with a short-lived code. You exchange the code for tokens server-side (or via PKCE from the browser).

The two JWT tokens

Ave returns two different JWTs on a successful token exchange. Understanding the difference is critical before writing any validation or auth integration.

id_token
access_token_jwt
access_token (opaque)

The id_token is an OIDC identity token. It proves who the user is. It is signed by Ave and its audience is your client ID.

{
  "iss": "https://aveid.net",
  "sub": "identity-uuid",
  "aud": "your_client_id",
  "exp": 1712345678,
  "iat": 1712342078,
  "auth_time": 1712342078,
  "azp": "your_client_id",
  "sid": "user-uuid",
  "nonce": "random-nonce-from-request",
  "name": "Alice Smith",
  "preferred_username": "alice",
  "email": "[email protected]",
  "picture": "https://avatars.aveid.net/..."
}

Profile claims (name, preferred_username, picture) are only present if you requested the profile scope. email is only present if you requested email and the selected identity has a verified email. nonce is only present if you included one in the authorization request.Use id_token for:

Establishing your app session (validating who logged in)
Convex custom auth integration
Any system that needs to verify Ave-issued identity

The access_token_jwt is a resource access JWT. It authorizes calls to Ave’s API. Its audience is Ave’s own resource audience, not your client ID.

{
  "iss": "https://aveid.net",
  "sub": "identity-uuid",
  "aud": "https://aveid.net",
  "exp": 1712345678,
  "iat": 1712342078,
  "scope": "openid profile email",
  "cid": "your_client_id",
  "sid": "user-uuid",
  "uid": "user-uuid"
}

cid is your client ID. uid is the user UUID, only present when the user_id scope was granted.Use access_token_jwt for:

Connector token-exchange grant (subjectToken field)
Passing to Ave API endpoints that accept JWT auth

The plain access_token is an opaque string, not a JWT. You cannot decode it.Use the opaque access_token for:

Calling GET /api/oauth/userinfo with Authorization: Bearer ACCESS_TOKEN
Any Ave API endpoint that documents accepting a bearer token

You can use either the opaque token or the JWT for Ave API endpoints. The opaque token is simpler when you do not need to inspect claims client-side.

If you are building Convex auth, use id_token. Its aud is your clientId, which is what Convex validates against. The access_token_jwt has aud: "https://aveid.net" — Convex will reject it because the audience does not match your app.

Claim reference

Full claim reference

Claim	Present in	Description
`iss`	Both JWTs	Always `https://aveid.net`
`sub`	Both JWTs	Identity UUID (changes per Ave identity)
`aud`	Both JWTs	`clientId` in `id_token`; `https://aveid.net` in `access_token_jwt`
`exp`	Both JWTs	Expiry timestamp (Unix seconds)
`iat`	Both JWTs	Issued-at timestamp
`sid`	Both JWTs	Permanent user UUID (stable across all identities)
`azp`	`id_token` only	Your client ID (authorized party)
`auth_time`	`id_token` only	When the user last authenticated
`nonce`	`id_token` only	Echo of the nonce from the authorization request
`name`	`id_token` only	Display name (requires `profile` scope)
`preferred_username`	`id_token` only	Identity handle (requires `profile` scope)
`email`	`id_token` only	Verified email address (requires `email` scope)
`picture`	`id_token` only	Avatar URL (requires `profile` scope)
`cid`	`access_token_jwt` only	Your client ID
`scope`	`access_token_jwt` only	Space-separated granted scopes
`uid`	`access_token_jwt` only	User UUID (only if `user_id` scope was granted)

Full flow

There are three ways to implement this — pick what fits your setup.

SDK (recommended)
Embed
Manual

Two function calls cover the entire flow. startPkceLogin generates PKCE, nonce, and state; stores them in sessionStorage; and redirects. finishPkceLogin reads them back, verifies the returned state, exchanges the code, and validates the returned tokens.

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

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

// /callback page
import { finishPkceLogin } from "@ave-id/sdk/client";

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

if (tokens) {
  // tokens.id_token, tokens.access_token, tokens.refresh_token, etc.
  // Token signatures and claims are already verified — create your session.
}

finishPkceLogin verifies token signatures internally — no separate validation step needed. It returns null when there’s no code in the URL, so it’s safe to mount on your callback route without guarding against non-callback page loads.

Use @ave-id/embed to show Ave login in a sheet or popup without leaving the page. Pass onTokens and PKCE, state, and code exchange are all handled automatically.

import { openAveSheet } from "@ave-id/embed";

// Show as a bottom sheet — openAvePopup works the same way
const { close } = await openAveSheet({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  scope: "openid profile email offline_access",
  onTokens: (tokens) => {
    // tokens.id_token, tokens.access_token, tokens.refresh_token, etc.
    // Token signatures and claims are already verified — create your session.
  },
  onError: ({ error, message }) => {
    console.error(error, message);
  },
});

For an inline embed on a dedicated auth page:

import { mountAveEmbed } from "@ave-id/embed";

const { destroy } = await mountAveEmbed({
  container: document.getElementById("auth-container"),
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  onTokens: (tokens) => {
    destroy();
    // Create your session
  },
  onError: ({ error }) => console.error(error),
});

onTokens requires no PKCE setup — the embed handles it. For full cryptographic validation of the returned id_token, pass it to verifyJwt from @ave-id/sdk after receiving tokens.

Use the individual helpers when you need full control — server-side token exchange, custom storage, or non-browser environments.

Create request context

Generate state, nonce, and PKCE parameters before redirecting. Store them in sessionStorage (browser) or your server session.

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

const codeVerifier = generateCodeVerifier();
const codeChallenge = await generateCodeChallenge(codeVerifier);
const state = generateNonce();
const nonce = generateNonce();

sessionStorage.setItem("ave_verifier", codeVerifier);
sessionStorage.setItem("ave_state", state);
sessionStorage.setItem("ave_nonce", nonce);

Redirect to Ave

Build the authorization URL and redirect the user.

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

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

window.location.href = url;

Handle callback securely

Ave redirects to your redirect_uri with ?code=...&state=.... Verify state before touching anything else.

const params = new URLSearchParams(window.location.search);
const code = params.get("code");
const returnedState = params.get("state");
const savedState = sessionStorage.getItem("ave_state");
const codeVerifier = sessionStorage.getItem("ave_verifier");
const savedNonce = sessionStorage.getItem("ave_nonce");

if (!returnedState || returnedState !== savedState) {
  throw new Error("State mismatch — possible CSRF attack");
}

// Clear immediately — single use
sessionStorage.removeItem("ave_state");
sessionStorage.removeItem("ave_verifier");
sessionStorage.removeItem("ave_nonce");

Exchange authorization code

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

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

The response includes access_token, access_token_jwt, id_token, refresh_token, expires_in, scope, and user.

Validate id_token and create session

Validate the id_token before trusting it. verifyJwt handles JWKS fetching, RS256 signature verification, and all required claim checks.

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

const claims = await verifyJwt(tokens.id_token, {
  audience: "YOUR_CLIENT_ID",
  nonce: savedNonce,
});

if (!claims) {
  throw new Error("Invalid id_token — signature or claims validation failed.");
}

// claims.sub    — identity UUID (use as your primary key)
// claims.email  — verified email (requires email scope)
// claims.name   — display name (requires profile scope)

Refresh token flow

Refresh tokens allow you to get new access tokens without requiring the user to log in again. They are only issued when you request offline_access scope.

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

const newTokens = await refreshToken(
  { clientId: "YOUR_CLIENT_ID", redirectUri: "https://yourapp.com/callback" },
  { refreshToken: storedRefreshToken }
);

// Store the new refresh token immediately
storeRefreshToken(newTokens.refresh_token);

For public PKCE clients, the rotating refresh token is the credential for this grant and remains bound to the registered clientId. This works for browser, desktop custom-protocol, and native application origins without a client secret.

Refresh tokens rotate on every use. Each successful refresh invalidates the old token and issues a new one. If you try to reuse an old refresh token, you will get invalid_grant and the server may revoke the entire token family as a security measure. Always persist the new refresh_token from the response before discarding the old one.

Userinfo endpoint

GET /api/oauth/userinfo returns live identity claims. Use this when you need fresh data that may not be in the cached id_token.

GET https://api.aveid.net/api/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

The returned claims depend on the scopes your access token has. The response always includes sub (identity UUID).

OIDC discovery & manual token validation

OIDC discovery document

Fetch the discovery document to programmatically get endpoint URLs and signing key locations:

GET https://aveid.net/.well-known/openid-configuration

{
  "issuer": "https://aveid.net",
  "authorization_endpoint": "https://aveid.net/signin",
  "token_endpoint": "https://api.aveid.net/api/oauth/token",
  "userinfo_endpoint": "https://api.aveid.net/api/oauth/userinfo",
  "jwks_uri": "https://aveid.net/.well-known/jwks.json",
  "scopes_supported": ["openid", "profile", "email", "offline_access", "user_id"],
  "response_types_supported": ["code"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

Manual ID token validation sequence

For non-JS environments or any library that validates tokens without the SDK, follow this order:

Fetch JWKS

GET https://aveid.net/.well-known/jwks.json. Cache the response and re-fetch only when you encounter an unknown kid.

Verify signature

Use the key matching the kid in the token header. Ave signs with RS256.

Check timestamps

Verify exp > now and iat <= now. Use a small clock tolerance (60 seconds) to handle drift.

Verify issuer and audience

iss must equal https://aveid.net. aud must equal your client ID. Reject anything else.

Verify nonce

If you sent a nonce in the authorization request, the id_token must contain the same value. This prevents replay attacks.

Edge cases

Authorization code expires in seconds

Don’t store the code and exchange later. Exchange immediately after validating state on the callback page.

Redirect URI must match exactly

Protocol, hostname, path, and query string must all match exactly. A trailing slash difference will cause invalid_grant. Register the exact URI you use.Development mode relaxes this only for localhost, loopback, and Expo Go redirect URLs so local ports can change without adding every callback. Production callback URLs still need explicit registration.

Missing id_token

The openid scope was not requested or was not granted. Add openid to your scope list.

Missing refresh_token

The offline_access scope was not requested or was not granted. Add offline_access to your scope list.

uid claim missing from access_token_jwt

The user_id scope was not included in the granted scopes. The uid claim and user_id token response field only appear when user_id is in the authorized scope list.

Start

OAuth

Frameworks

Capabilities

OAuth authorization code flow

The two JWT tokens

Claim reference

Full flow

Refresh token flow

Userinfo endpoint

OIDC discovery & manual token validation

Edge cases

​The two JWT tokens

​Claim reference

​Full flow

​Refresh token flow

​Userinfo endpoint

​OIDC discovery & manual token validation

​Edge cases

The two JWT tokens

Claim reference

Full flow

Refresh token flow

Userinfo endpoint

OIDC discovery & manual token validation

Edge cases