Convex custom auth

Convex supports custom auth providers via its custom auth feature. Ave works as a drop-in OIDC provider. This guide explains exactly what to configure, which token to pass, and what Convex does with it.

Which token to use

Always pass id_token to Convex. Never pass access_token_jwt. This is the most common mistake when integrating Ave with Convex.

Ave returns two JWTs. They look similar but serve different purposes and have different audiences:

Token	`aud` claim	Purpose
`id_token`	Your `clientId`	Identity assertion — proves who the user is
`access_token_jwt`	`https://aveid.net`	API authorization — grants access to Ave’s resources

Convex validates the aud claim against the applicationID you configure. If you use access_token_jwt, Convex will reject it because its audience is https://aveid.net, not your client ID.

Auth config

Add Ave as a custom provider in convex/auth.config.ts:

export default {
  providers: [
    {
      domain: "https://aveid.net",
      applicationID: "your_client_id",
    },
  ],
};

domain maps to the iss (issuer) claim in the token. Ave’s issuer is https://aveid.net. Convex fetches {domain}/.well-known/openid-configuration to discover the JWKS endpoint automatically.

What Convex validates

When you call convex.setAuth(idToken) or equivalent, Convex:

Fetches https://aveid.net/.well-known/openid-configuration
Gets the JWKS URL from the discovery document
Downloads and caches signing keys
Verifies the JWT signature (RS256)
Checks iss === "https://aveid.net"
Checks aud === "your_client_id" (the applicationID you configured)
Checks exp > now

If all checks pass, Convex considers the user authenticated and the identity is available as ctx.auth.getUserIdentity().

What claims Convex exposes

After a successful auth check, ctx.auth.getUserIdentity() returns:

{
  subject: "identity-uuid",         // id_token `sub` — Ave identity UUID
  issuer: "https://aveid.net",  // id_token `iss`
  name: "Alice Smith",              // id_token `name` (if profile scope)
  email: "[email protected]",       // id_token `email` (if email scope)
  pictureUrl: "https://...",        // id_token `picture` (if profile scope)
  // plus any other claims in the token
}

The subject is the Ave identity UUID — this is the value you should use as your primary user identifier in Convex.

The sub in the id_token is the identity UUID, not a permanent user UUID. A single Ave user can have multiple identities. If you need a stable cross-identity identifier, request the user_id scope — but note that user_id is in access_token_jwt (the uid claim), not in id_token. For most apps, the identity UUID is the right identifier.

Full implementation

Configure auth.config.ts

// convex/auth.config.ts
export default {
  providers: [
    {
      domain: "https://aveid.net",
      applicationID: process.env.AVE_CLIENT_ID!,
    },
  ],
};

Store your client ID in an environment variable. Do not hardcode it.

Complete the Ave OAuth flow

Follow the OAuth authorization code flow to get tokens. You need the openid scope at minimum — without it, Ave does not return an id_token.

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

const tokens = await exchangeCode(
  { clientId: process.env.AVE_CLIENT_ID!, redirectUri: REDIRECT_URI },
  { code, codeVerifier }
);

// id_token is only present when openid scope was requested
if (!tokens.id_token) {
  throw new Error("No id_token returned — did you include the openid scope?");
}

Pass id_token to Convex

import { ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

// Set the Ave id_token as the auth token
convex.setAuth(async () => tokens.id_token);

In a React app, use ConvexProviderWithAuth or the useAuth hook from your auth state to keep the token fresh.

Use the identity in mutations and queries

// convex/users.ts
import { mutation, query } from "./_generated/server";

export const getOrCreateUser = mutation(async (ctx) => {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) throw new Error("Not authenticated");

  // identity.subject is the Ave identity UUID
  const existing = await ctx.db
    .query("users")
    .withIndex("byAveId", q => q.eq("aveIdentityId", identity.subject))
    .first();

  if (existing) return existing;

  return await ctx.db.insert("users", {
    aveIdentityId: identity.subject,
    name: identity.name ?? "Unknown",
    email: identity.email,
    imageUrl: identity.pictureUrl,
  });
});

Handle token refresh (recommended: Ave Session)

id_token expires (check exp claim). Do not pass a static tokens.id_token to setAuth — Convex validates exp on every request. Prefer Ave Session (AveSession + wireAveSessionToConvex) so refresh is single-flight, persisted, and runs before expiry.Manual refresh (if you are not using AveSession yet):

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

const newTokens = await refreshToken(
  { clientId: CLIENT_ID, redirectUri: REDIRECT_URI },
  { refreshToken: storedRefreshToken }
);

// Persist new refresh_token immediately if the server rotated it — then:
convex.setAuth(async () => newTokens.id_token);

Default token lifetime is often about one hour (expires_in). Quick Ave has no refresh token — upgrade to a registered app with offline_access. See also Sessions still flaky below.

Sessions still flaky

If users drop out after ~one hour, or behavior feels random even with offline_access:

Cause	What to do
Quick Ave (`origin:…` clientId)	No refresh tokens — upgrade
Missing `offline_access`	Request it — refresh tokens are not issued without it
Using static `id_token` in `setAuth`	Use a function that returns a fresh token (Ave Session)
Refresh rotation not saved	After every refresh, persist the new `refresh_token` before other requests run
Concurrent refresh	Two callers refreshing at once can invalidate rotated refresh tokens — use single-flight (`AveSession`)
Cold start	Ensure `hydrate()` (or equivalent) finishes before authenticated Convex calls

Complete id_token payload reference

For your reference, here is the full id_token payload shape:

{
  "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": "nonce-from-request",
  "name": "Alice Smith",
  "preferred_username": "alice",
  "email": "[email protected]",
  "picture": "https://avatars.aveid.net/..."
}

Profile claims are only present when the corresponding scope was granted.

Troubleshooting

Convex rejects the token with 'invalid audience'

You are passing access_token_jwt instead of id_token. The access_token_jwt has aud: "https://aveid.net" — Convex expects aud === your_client_id. Always use id_token.

No id_token in the token response

You did not include openid in the scope parameter of the authorization request. id_token is only issued when the openid scope is granted. Add openid to your scope list.

Convex says issuer does not match

Verify that domain in auth.config.ts is exactly https://aveid.net. The iss claim in Ave tokens is https://aveid.net. If you have set a custom issuer via the OIDC_ISSUER environment variable in your Ave server, use that value instead.

getUserIdentity() returns null

The token may have expired, or convex.setAuth was not called before the query/mutation ran. Make sure your auth state provider calls convex.setAuth before any authenticated Convex calls.

Clock skew errors

Server clocks must be reasonably in sync. Convex allows a small tolerance. If you see exp validation failures on otherwise valid tokens, check that your backend server time is accurate.

Start

OAuth

Frameworks

Capabilities

Convex custom auth

Which token to use

Auth config

What Convex validates

What claims Convex exposes

Full implementation

Sessions still flaky

Complete id_token payload reference

Troubleshooting

​Which token to use

​Auth config

​What Convex validates

​What claims Convex exposes

​Full implementation

​Sessions still flaky

​Complete id_token payload reference

​Troubleshooting

Which token to use

Auth config

What Convex validates

What claims Convex exposes

Full implementation

Sessions still flaky

Complete id_token payload reference

Troubleshooting