Convex Integration (OIDC)

Prerequisites

• Issuer (iss): https://entity-auth.com
• JWKS: https://entity-auth.com/.well-known/jwks.json
• Application ID (aud): convex (or your custom value)

Configure Convex

You can configure Convex in the dashboard (Authentication → OIDC) or in code.

// convex/auth.config.ts
import { defineAuth } from "convex/server";

export default defineAuth({
  providers: [
    {
      type: "oidc",
      issuerURL: "https://entity-auth.com",
      jwksURL: "https://entity-auth.com/.well-known/jwks.json",
      applicationID: "convex", // must match your JWT aud
    },
  ],
});

Deploy your Convex backend after adding this file.

Client wiring (ConvexProviderWithAuth)

Pass Entity Auth’s access token to Convex. Example hook:

import { useCallback, useMemo } from "react";
import { ConvexProviderWithAuth } from "convex/react";
import { entityAuthClient } from "@/entity-auth/auth-client";

function useAuthFromEntityAuth() {
  const fetchAccessToken = useCallback(async ({ forceRefreshToken }: { forceRefreshToken: boolean }) => {
    if (forceRefreshToken) await entityAuthClient.refresh();
    return entityAuthClient.getAccessToken();
  }, []);

  return useMemo(
    () => ({
      isLoading: false,
      isAuthenticated: Boolean(entityAuthClient.getAccessToken()),
      fetchAccessToken,
    }),
    [fetchAccessToken]
  );
}

// Usage at app root:
// <ConvexProviderWithAuth client={convex} useAuth={useAuthFromEntityAuth}>...</ConvexProviderWithAuth>

React hooks integration

If you want a higher-level hook that combines Entity Auth state with live Convex queries, see the Convex React adapter:

• /docs/integrations/convex-react

Identity mapping (eaSub)

• If your JWT lacks an email claim, match users by subject (sub).
• Store eaSub = JWT.sub on your user record the first time you see the identity.
• Ensure backfill flows or guardrails link sessions via eaSub when email is missing.

Troubleshooting

• Decode a token in the browser console:

const payload = JSON.parse(atob(token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/")));
console.log(payload.iss, payload.aud, payload.sub);

• Verify on Convex Dashboard → Authentication → Test token.
• Common fixes:
  • Issuer mismatch: Convex must use https://entity-auth.com (not a tenant subdomain).
  • Audience mismatch: Convex applicationID must equal the token’s aud.
  • JWKS errors: /.well-known/jwks.json must return a key; set EA_JWT_PUBLIC_KEY_PEM_B64 if needed.