convex-auth-skill

Name: convex-auth-skill
Author: PolarCoding85

17stars3forks

How to install convex-auth-skill?

polarcoding85/convex-agent-skillz/convex-auth-skill

$npx -y skills add PolarCoding85/convex-agent-skillz --skill convex-auth-skill

Installs into the current project.

Summary

Core authentication patterns for Convex backends. Use when implementing auth checks in functions, storing users in database, creating auth helpers, or debugging auth issues. Works with any auth provider (Clerk, WorkOS, Auth0, etc.).

Files · 1

View on GitHub

SKILL.md

1	# Convex Authentication - Core Patterns
2
3	This skill covers universal auth patterns that work with ANY authentication provider.
4
5	## Auth in Functions
6
7	Access the authenticated user via `ctx.auth.getUserIdentity()`:
8
9	```typescript
10	import { query, mutation, action } from './_generated/server';
11
12	export const myQuery = query({
13	args: {},
14	handler: async (ctx) => {
15	const identity = await ctx.auth.getUserIdentity();
16	if (identity === null) {
17	throw new Error('Not authenticated');
18	}
19	// identity.tokenIdentifier - unique across providers
20	// identity.subject - user ID from provider
21	// identity.email, identity.name, etc. (if configured)
22	}
23	});
24	```
25
26	### UserIdentity Fields
27
28	\| Field \| Guaranteed \| Description \|
29	\| ----------------- \| ------------------ \| ------------------------------------- \|
30	\| `tokenIdentifier` \| ✅ \| Unique ID (subject + issuer combined) \|
31	\| `subject` \| ✅ \| User ID from auth provider \|
32	\| `issuer` \| ✅ \| Auth provider domain \|
33	\| `email` \| Provider-dependent \| User's email \|
34	\| `name` \| Provider-dependent \| Display name \|
35	\| `pictureUrl` \| Provider-dependent \| Avatar URL \|
36
37	## Critical: Race Condition Prevention
38
39	Problem: Queries can execute before auth is validated on page load.
40
41	Client-side: Always use `useConvexAuth()` from `convex/react`, NOT your provider's hook:
42
43	```typescript
44	// ✅ Correct - waits for Convex to validate token
45	import { useConvexAuth } from 'convex/react';
46	const { isLoading, isAuthenticated } = useConvexAuth();
47
48	// ❌ Wrong - only checks provider, not Convex validation
49	const { isSignedIn } = useAuth(); // from @clerk/clerk-react
50	```
51
52	Skip queries until authenticated:
53
54	```typescript
55	const user = useQuery(api.users.current, isAuthenticated ? {} : 'skip');
56	```
57
58	Use Convex auth components:
59
60	```typescript
61	import { Authenticated, Unauthenticated, AuthLoading } from "convex/react";
62
63	<Authenticated>
64	<Content /> {/* Queries here are safe */}
65	</Authenticated>
66	<Unauthenticated>
67	<SignInButton />
68	</Unauthenticated>
69	```
70
71	## Storing Users in Database
72
73	See [USERS.md](references/USERS.md) for complete patterns including:
74
75	- Schema design with indexes
76	- Storing users via client mutation
77	- Storing users via webhooks (recommended for production)
78	- Helper functions for user lookup
79
80	## Custom Auth Wrappers
81
82	Create authenticated function wrappers using `convex-helpers`:
83
84	```typescript
85	// convex/lib/auth.ts
86	import {
87	query,
88	mutation,
89	action,
90	QueryCtx,
91	MutationCtx,
92	ActionCtx
93	} from './_generated/server';
94	import {
95	customQuery,
96	customMutation,
97	customAction,
98	customCtx
99	} from 'convex-helpers/server/customFunctions';
100	import { ConvexError } from 'convex/values';
101
102	async function requireAuth(ctx: QueryCtx \| MutationCtx \| ActionCtx) {
103	const identity = await ctx.auth.getUserIdentity();
104	if (!identity) {
105	throw new ConvexError('Not authenticated');
106	}
107	return identity;
108	}
109
110	export const authQuery = customQuery(
111	query,
112	customCtx(async (ctx) => {
113	const identity = await requireAuth(ctx);
114	return { identity };
115	})
116	);
117
118	export const authMutation = customMutation(
119	mutation,
120	customCtx(async (ctx) => {
121	const identity = await requireAuth(ctx);
122	return { identity };
123	})
124	);
125
126	export const authAction = customAction(
127	action,
128	customCtx(async (ctx) => {
129	const identity = await requireAuth(ctx);
130	return { identity };
131	})
132	);
133	```
134
135	Usage:
136
137	```typescript
138	import { authQuery } from './lib/auth';
139
140	export const myProtectedQuery = authQuery({
141	args: {},
142	handler: async (ctx) => {
143	// ctx.identity is guaranteed to exist
144	const userId = ctx.identity.subject;
145	}
146	});
147	```
148
149	## HTTP Actions with Auth
150
151	Pass JWT in Authorization header:
152
153	```typescript
154	// Client
155	fetch('https://your-deployment.convex.site/api/endpoint', {
156	headers: { Authorization: `Bearer ${jwtToken}` }
157	});
158
159	// convex/http.ts
160	import { httpAction } from './_generated/server';
161
162	export const myEndpoint = httpAction(async (ctx, request) => {
163	const identity = await ctx.auth.getUserIdentity();
164	if (!identity) {
165	return new Response('Unauthorized', { status: 401 });
166	}
167	// ...
168	});
169	```
170
171	## Debugging Checklist
172
173	See [DEBUG.md](references/DEBUG.md) for detailed troubleshooting steps.
174
175	Quick checks:
176
177	1. `ctx.auth.getUserIdentity()` returns `null`?
178	- Check if query runs before auth completes (use `"skip"` pattern)
179	- Check auth.config.ts is deployed (`npx convex dev`)
180	2. Check Settings > Authentication in Convex Dashboard
181	3. Verify JWT token at https://jwt.io

People who liked this also viewed

6 picks

Type

convex-auth-skill

17stars3forks

View on GitHub

How to install convex-auth-skill?

polarcoding85/convex-agent-skillz/convex-auth-skill

$npx -y skills add PolarCoding85/convex-agent-skillz --skill convex-auth-skill

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Convex Authentication - Core Patterns
2
3	This skill covers universal auth patterns that work with ANY authentication provider.
4
5	## Auth in Functions
6
7	Access the authenticated user via `ctx.auth.getUserIdentity()`:
8
9	```typescript
10	import { query, mutation, action } from './_generated/server';
11
12	export const myQuery = query({
13	args: {},
14	handler: async (ctx) => {
15	const identity = await ctx.auth.getUserIdentity();
16	if (identity === null) {
17	throw new Error('Not authenticated');
18	}
19	// identity.tokenIdentifier - unique across providers
20	// identity.subject - user ID from provider
21	// identity.email, identity.name, etc. (if configured)
22	}
23	});
24	```
25
26	### UserIdentity Fields
27
28	\| Field \| Guaranteed \| Description \|
29	\| ----------------- \| ------------------ \| ------------------------------------- \|
30	\| `tokenIdentifier` \| ✅ \| Unique ID (subject + issuer combined) \|
31	\| `subject` \| ✅ \| User ID from auth provider \|
32	\| `issuer` \| ✅ \| Auth provider domain \|
33	\| `email` \| Provider-dependent \| User's email \|
34	\| `name` \| Provider-dependent \| Display name \|
35	\| `pictureUrl` \| Provider-dependent \| Avatar URL \|
36
37	## Critical: Race Condition Prevention
38
39	Problem: Queries can execute before auth is validated on page load.
40
41	Client-side: Always use `useConvexAuth()` from `convex/react`, NOT your provider's hook:
42
43	```typescript
44	// ✅ Correct - waits for Convex to validate token
45	import { useConvexAuth } from 'convex/react';
46	const { isLoading, isAuthenticated } = useConvexAuth();
47
48	// ❌ Wrong - only checks provider, not Convex validation
49	const { isSignedIn } = useAuth(); // from @clerk/clerk-react
50	```
51
52	Skip queries until authenticated:
53
54	```typescript
55	const user = useQuery(api.users.current, isAuthenticated ? {} : 'skip');
56	```
57
58	Use Convex auth components:
59
60	```typescript
61	import { Authenticated, Unauthenticated, AuthLoading } from "convex/react";
62
63	<Authenticated>
64	<Content /> {/* Queries here are safe */}
65	</Authenticated>
66	<Unauthenticated>
67	<SignInButton />
68	</Unauthenticated>
69	```
70
71	## Storing Users in Database
72
73	See [USERS.md](references/USERS.md) for complete patterns including:
74
75	- Schema design with indexes
76	- Storing users via client mutation
77	- Storing users via webhooks (recommended for production)
78	- Helper functions for user lookup
79
80	## Custom Auth Wrappers
81
82	Create authenticated function wrappers using `convex-helpers`:
83
84	```typescript
85	// convex/lib/auth.ts
86	import {
87	query,
88	mutation,
89	action,
90	QueryCtx,
91	MutationCtx,
92	ActionCtx
93	} from './_generated/server';
94	import {
95	customQuery,
96	customMutation,
97	customAction,
98	customCtx
99	} from 'convex-helpers/server/customFunctions';
100	import { ConvexError } from 'convex/values';
101
102	async function requireAuth(ctx: QueryCtx \| MutationCtx \| ActionCtx) {
103	const identity = await ctx.auth.getUserIdentity();
104	if (!identity) {
105	throw new ConvexError('Not authenticated');
106	}
107	return identity;
108	}
109
110	export const authQuery = customQuery(
111	query,
112	customCtx(async (ctx) => {
113	const identity = await requireAuth(ctx);
114	return { identity };
115	})
116	);
117
118	export const authMutation = customMutation(
119	mutation,
120	customCtx(async (ctx) => {
121	const identity = await requireAuth(ctx);
122	return { identity };
123	})
124	);
125
126	export const authAction = customAction(
127	action,
128	customCtx(async (ctx) => {
129	const identity = await requireAuth(ctx);
130	return { identity };
131	})
132	);
133	```
134
135	Usage:
136
137	```typescript
138	import { authQuery } from './lib/auth';
139
140	export const myProtectedQuery = authQuery({
141	args: {},
142	handler: async (ctx) => {
143	// ctx.identity is guaranteed to exist
144	const userId = ctx.identity.subject;
145	}
146	});
147	```
148
149	## HTTP Actions with Auth
150
151	Pass JWT in Authorization header:
152
153	```typescript
154	// Client
155	fetch('https://your-deployment.convex.site/api/endpoint', {
156	headers: { Authorization: `Bearer ${jwtToken}` }
157	});
158
159	// convex/http.ts
160	import { httpAction } from './_generated/server';
161
162	export const myEndpoint = httpAction(async (ctx, request) => {
163	const identity = await ctx.auth.getUserIdentity();
164	if (!identity) {
165	return new Response('Unauthorized', { status: 401 });
166	}
167	// ...
168	});
169	```
170
171	## Debugging Checklist
172
173	See [DEBUG.md](references/DEBUG.md) for detailed troubleshooting steps.
174
175	Quick checks:
176
177	1. `ctx.auth.getUserIdentity()` returns `null`?
178	- Check if query runs before auth completes (use `"skip"` pattern)
179	- Check auth.config.ts is deployed (`npx convex dev`)
180	2. Check Settings > Authentication in Convex Dashboard
181	3. Verify JWT token at https://jwt.io

People who liked this also viewed

6 picks

Type