Convex Auth Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• src/convex.ts
• src/types.ts
• README.md
• package.json
• src/hooks.ts

The Convex Auth Configuration is a specialized module within the @pcstyle/auth SDK designed to integrate WorkOS authentication with Convex backend services. Its primary purpose is to generate a valid configuration object that Convex uses to verify JSON Web Tokens (JWTs) issued by WorkOS, enabling secure access to database functions based on the user's identity.

This configuration bridges the gap between the frontend authentication state (managed by WorkOS AuthKit) and the backend data layer (Convex), ensuring that only authenticated users with valid tokens can interact with protected resources.
Sources: src/convex.ts:1-12, README.md:65-69

Core Configuration Logic

The configuration is centered around the createConvexAuthConfig function. This function accepts a WorkOS Client ID and returns a structured object containing JWT providers. This object is required by Convex to establish trust with WorkOS as an OIDC (OpenID Connect) provider.

JWT Provider Structure

The configuration defines two distinct JWT providers to ensure compatibility with different WorkOS token issuance patterns:

1. Standard API Provider: Uses https://api.workos.com/ as the issuer.
2. User Management Provider: Uses a client-specific URL https://api.workos.com/user_management/${clientId} as the issuer.

Both providers utilize the RS256 algorithm and fetch public keys from the WorkOS JSON Web Key Set (JWKS) endpoint.
Sources: src/convex.ts:13-35

The diagram above illustrates how the Client ID is transformed into multiple JWT providers to enable token verification within Convex.

Data Models and Types

The system defines specific interfaces to ensure type safety between the WorkOS identity provider and the Convex database records.

Convex User Record

The ConvexUser interface represents how user data is structured within the Convex database after authentication.

Field	Type	Description
_id	string	Internal Convex document ID
authId	string	The external WorkOS user ID
email	string	User's email address
name	string (Optional)	User's display name
avatarUrl	string (Optional)	URL to user's profile picture
role	string	User's permission level/role
createdAt	number	Creation timestamp
updatedAt	number	Last update timestamp

Sources: src/types.ts:40-50

Implementation Flow

To implement this configuration, developers typically export the result of createConvexAuthConfig from a dedicated configuration file in their Convex directory.

Configuration Sequence

This sequence shows how the configuration generated by the SDK is used by Convex to validate tokens requested by the frontend.
Sources: README.md:65-69, src/convex.ts:20-33

Code Example: convex/auth.config.ts

import { createConvexAuthConfig } from '@pcstyle/auth/convex';

// This export is consumed by the Convex CLI/Dashboard
export default createConvexAuthConfig(process.env.WORKOS_CLIENT_ID);

Sources: src/convex.ts:7-11, src/convex.ts:38

Integration with Frontend Hooks

While the configuration handles the backend verification, the @pcstyle/auth hooks provide the necessary interface to manage the user state that eventually interacts with Convex. The useAuth hook returns an AuthState which includes the isAuthenticated flag and the User object, both of which are critical for determining when to trigger Convex queries.
Sources: src/hooks.ts:18-28, src/types.ts:17-21

The Convex Auth Configuration serves as the security foundation for the backend, allowing developers to trust the identity of users provided by WorkOS and map them to internal ConvexUser records. By automating the JWKS and issuer URL construction, it reduces the complexity of manual OIDC setup.