How to use stack-auth with convex?

[signal patrol]

^

[undone ibex]

Hi @signal patrol. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

I'm sorry, but the knowledge sources provided do not contain any information about "stack-auth" or how to use it with Convex. If you meant a different authentication library (such as Convex Auth, Auth.js/NextAuth, or Clerk), please clarify, and I can provide detailed instructions based on the available documentation.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@signal patrol Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[signal patrol]

StackAuth or how do i implement a custom JWT auth provider/

StackAuth or how do i implement a custom JWT auth provider/ @undone ibex

[undone ibex]

Let me check the knowledge base for you again. One moment! :books:

---

To implement a custom JWT auth provider with Convex, you need to configure your Convex backend to accept and validate JWTs issued by your own authentication system. Here’s how you can do it:

1. Server-side Integration

In your convex/auth.config.js (or .ts), add a provider with type: "customJwt" and specify the required fields:

export default {  
  providers: [  
    {  
      type: "customJwt",  
      applicationID: "your-application-id", // (optional, matches JWT 'aud' claim)
      issuer: "<https://your.issuer.url.com",> // must match JWT 'iss' claim
      jwks: "<https://your.issuer.url.com/.well-known/jwks.json",> // JWKS endpoint
      algorithm: "RS256", // or "ES256"
    },  
  ],  
};

• issuer must exactly match the iss field in your JWT.
• If you specify applicationID, it must match the aud field in your JWT.
• The jwks URL should point to a public endpoint serving your JSON Web Key Set, which Convex will use to verify JWT signatures.
• Only RS256 and ES256 algorithms are supported.

If your JWT provider does not support OIDC discovery, you must ensure the JWKS endpoint is available and returns the correct keys. You can use a custom API route to proxy or serve the JWKS if your provider returns an unsupported content type or formatCustom JWT Provider.

2. Client-side Integration

On the client, you need to provide a way for Convex to fetch the JWT and refresh it as needed. This is typically done by passing a custom hook to ConvexProviderWithAuth:

function useAuthFromYourProvider() {
  // Replace with your auth logic
  const { isLoading, isAuthenticated, getToken } = useYourAuthHook();
  const fetchAccessToken = useCallback(
    async ({ forceRefreshToken }) => {
      return await getToken({ ignoreCache: forceRefreshToken });
    },
    [getToken],
  );
  return useMemo(
    () => ({
      isLoading,
      isAuthenticated: isAuthenticated ?? false,
      fetchAccessToken,
    }),
    [isLoading, isAuthenticated, fetchAccessToken],
  );
}

Then, wrap your app with ConvexProviderWithAuth and pass your custom hook:

<YourAuthProvider>
  <ConvexProviderWithAuth client={convex} useAuth={useAuthFromYourProvider}>
    <App />
  </ConvexProviderWithAuth>
</YourAuthProvider>

Client-side integration example

3. Debugging

If you encounter errors like "No auth provider found matching the given token," double-check that the iss and aud fields in your JWT match the issuer and applicationID in your Convex config exactly. Use jwt.io to inspect your token and verify the claims. Also, ensure your JWKS endpoint is publicly accessible and returns the correct content type (application/json is now supported)Custom JWT Provider.

---

If you meant "StackAuth" as a specific library, the knowledge sources do not mention it. The above instructions are for implementing a custom JWT provider with Convex, which is the recommended approach for custom authentication flows.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@signal patrol Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[signal patrol]

@undone ibex can you give me a file structure in nextjs

[undone ibex]

Let me check the knowledge base for you again. One moment! :books:

---

Certainly! Here’s an example file structure for implementing a custom JWT auth provider with Convex in a Next.js project, based on the knowledge sources:

my-nextjs-app/
├── app/
│   ├── ConvexClientProvider.tsx      # Client component to wrap ConvexProviderWithAuth
│   ├── layout.tsx                    # Root layout, wraps children with ConvexClientProvider
│   └── page.tsx                      # Example page using Convex queries
├── convex/
│   ├── auth.config.ts                # Convex auth config for custom JWT provider
│   ├── http.ts                       # (Optional) Expose JWKS endpoint if needed
│   └── schema.ts                     # Convex schema
├── .env.local                        # Environment variables (e.g., JWKS URL, issuer)
├── package.json
└── ...

Key files and their roles:

• convex/auth.config.ts: Configures Convex to accept your custom JWT provider by specifying type: "customJwt", issuer, jwks, etc.
  See example config
• convex/http.ts: (Optional) If you need to expose your JWKS endpoint for Convex to verify JWTs, you can add HTTP routes here
  See example
• app/ConvexClientProvider.tsx: Implements and exports a client component that wraps your app in ConvexProviderWithAuth and provides a custom useAuth hook for fetching JWTs.
• app/layout.tsx: Wraps your app with ConvexClientProvider.
• .env.local: Stores environment variables such as your JWKS URL, issuer, and Convex URL.

This structure follows the patterns shown in the Convex documentation for custom JWT providers and Next.js integration. If you need more detailed examples for any file, let me know!
Reference: Custom JWT Provider
Reference: Next.js Quickstart

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: