Convex Auth

Complete guide for authentication and authorization in Convex apps using @convex-dev/auth.

Critical Rules

1. Always validate auth server-side — client-side <Authenticated> is UX only, not security.
2. Use getAuthUserId(ctx) in every query/mutation that needs auth — never trust the client.
3. Authenticated !== Authorized — always check permissions after confirming identity.
4. Use expo-secure-store for React Native token storage — never AsyncStorage.
5. Polyfills are required for React Native — import them before any other code in _layout.tsx.
6. Callback URLs use .site not .cloud — format: https://<deployment>.convex.site/api/auth/callback/<provider>.
7. Separate OAuth apps for development and production environments.
8. Use ConvexError for auth/authz errors to provide structured error responses.

Table of Contents