convex-setup-auth

Name: convex-setup-auth
Author: get-convex

89kinstalls8forks

How to install convex-setup-auth?

get-convex/agent-skills/convex-setup-auth

$npx -y skills add get-convex/agent-skills --skill convex-setup-auth

Installs into the current project.

Summary

Sets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.

Files · 1

View on GitHub

SKILL.md

1	# Convex Authentication Setup
2
3	Implement secure authentication in Convex with user management and access
4	control.
5
6	## When to Use
7
8	- Setting up authentication for the first time
9	- Implementing user management (users table, identity mapping)
10	- Creating authentication helper functions
11	- Setting up auth providers (Convex Auth, Clerk, WorkOS AuthKit, Auth0, custom
12	JWT)
13
14	## When Not to Use
15
16	- Auth for a non-Convex backend
17	- Pure OAuth/OIDC documentation without a Convex implementation
18	- Debugging unrelated bugs that happen to surface near auth code
19	- The auth provider is already fully configured and the user only needs a
20	one-line fix
21
22	## First Step: Choose the Auth Provider
23
24	Convex supports multiple authentication approaches. Do not assume a provider.
25
26	Before writing setup code:
27
28	1. Ask the user which auth solution they want, unless the repository already
29	makes it obvious
30	2. If the repo already uses a provider, continue with that provider unless the
31	user wants to switch
32	3. If the user has not chosen a provider and the repo does not make it obvious,
33	ask before proceeding
34
35	Common options:
36
37	- [Convex Auth](https://docs.convex.dev/auth/convex-auth) - good default when
38	the user wants auth handled directly in Convex
39	- [Clerk](https://docs.convex.dev/auth/clerk) - use when the app already uses
40	Clerk or the user wants Clerk's hosted auth features
41	- [WorkOS AuthKit](https://docs.convex.dev/auth/authkit/) - use when the app
42	already uses WorkOS or the user wants AuthKit specifically
43	- [Auth0](https://docs.convex.dev/auth/auth0) - use when the app already uses
44	Auth0
45	- Custom JWT provider - use when integrating an existing auth system not covered
46	above
47
48	Look for signals in the repo before asking:
49
50	- Dependencies such as `@clerk/`, `@workos-inc/`, `@auth0/*`, or Convex Auth
51	packages
52	- Existing files such as `convex/auth.config.ts`, auth middleware, provider
53	wrappers, or login components
54	- Environment variables that clearly point at a provider
55
56	## After Choosing a Provider
57
58	Read the provider's official guide and the matching local reference file:
59
60	- Convex Auth: [official docs](https://docs.convex.dev/auth/convex-auth), then
61	`references/convex-auth.md`
62	- Clerk: [official docs](https://docs.convex.dev/auth/clerk), then
63	`references/clerk.md`
64	- WorkOS AuthKit: [official docs](https://docs.convex.dev/auth/authkit/), then
65	`references/workos-authkit.md`
66	- Auth0: [official docs](https://docs.convex.dev/auth/auth0), then
67	`references/auth0.md`
68
69	The local reference files contain the concrete workflow, expected files and env
70	vars, gotchas, and validation checks.
71
72	Use those sources for:
73
74	- package installation
75	- client provider wiring
76	- environment variables
77	- `convex/auth.config.ts` setup
78	- login and logout UI patterns
79	- framework-specific setup for React, Vite, or Next.js
80
81	For shared auth behavior, use the official Convex docs as the source of truth:
82
83	- [Auth in Functions](https://docs.convex.dev/auth/functions-auth) for
84	`ctx.auth.getUserIdentity()`
85	- [Storing Users in the Convex Database](https://docs.convex.dev/auth/database-auth)
86	for optional app-level user storage
87	- [Authentication](https://docs.convex.dev/auth) for general auth and
88	authorization guidance
89	- [Convex Auth Authorization](https://labs.convex.dev/auth/authz) when the
90	provider is Convex Auth
91
92	Prefer official docs over recalled steps, because provider CLIs and Convex Auth
93	internals change between versions. Inventing setup from memory risks outdated
94	patterns. For third-party providers, only add app-level user storage if the app
95	actually needs user documents in Convex. Not every app needs a `users` table.
96	For Convex Auth, follow the Convex Auth docs and built-in auth tables rather
97	than adding a parallel `users` table plus `storeUser` flow, because Convex Auth
98	already manages user records internally. After running provider initialization
99	commands, verify generated files and complete the post-init wiring steps the
100	provider reference calls out. Initialization commands rarely finish the entire
101	integration.
102
103	## Core Pattern: Protecting Backend Functions
104
105	The most common auth task is checking identity in Convex functions.
106
107	```ts
108	// Bad: trusting a client-provided userId
109	export const getMyProfile = query({
110	args: { userId: v.id("users") },
111	handler: async (ctx, args) => {
112	return await ctx.db.get(args.userId);
113	},
114	});
115	```
116
117	```ts
118	// Good: verifying identity server-side
119	export const getMyProfile = query({
120	args: {},
121	handler: async (ctx) => {
122	const identity = await ctx.auth.getUserIdentity();
123	if (!identity) throw new Error("Not authenticated");
124
125	return await ctx.db
126	.query("users")
127	.withIndex("by_tokenIdentifier", (q) =>
128	q.eq("tokenIdentifier", identity.tokenIdentifier),
129	)
130	.unique();
131	},
132	});

People who liked this also viewed

6 picks

Type

azure-storageAzure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier,SkillsJul 2026471k1.3k
supabase-postgres-best-practicesPostgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.SkillsJul 2026302k2.4k
supabaseUse when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, SkillsJul 2026179k2.4k
convex-quickstartCreates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.SkillsJul 202690k39
convex-performance-auditAudits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.SkillsJul 202689k39
convex-migration-helperPlans Convex schema and data migrations with widen-migrate-narrow and @convex-dev/migrations. Use for breaking schema changes, backfills, table reshaping, or zero-downtime rollouts.SkillsJul 202689k39

convex-setup-auth

89kinstalls8forks

View on GitHub

How to install convex-setup-auth?

get-convex/agent-skills/convex-setup-auth

$npx -y skills add get-convex/agent-skills --skill convex-setup-auth

Installs into the current project.

Summary

Sets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.

Files · 1

View on GitHub

SKILL.md

1	# Convex Authentication Setup
2
3	Implement secure authentication in Convex with user management and access
4	control.
5
6	## When to Use
7
8	- Setting up authentication for the first time
9	- Implementing user management (users table, identity mapping)
10	- Creating authentication helper functions
11	- Setting up auth providers (Convex Auth, Clerk, WorkOS AuthKit, Auth0, custom
12	JWT)
13
14	## When Not to Use
15
16	- Auth for a non-Convex backend
17	- Pure OAuth/OIDC documentation without a Convex implementation
18	- Debugging unrelated bugs that happen to surface near auth code
19	- The auth provider is already fully configured and the user only needs a
20	one-line fix
21
22	## First Step: Choose the Auth Provider
23
24	Convex supports multiple authentication approaches. Do not assume a provider.
25
26	Before writing setup code:
27
28	1. Ask the user which auth solution they want, unless the repository already
29	makes it obvious
30	2. If the repo already uses a provider, continue with that provider unless the
31	user wants to switch
32	3. If the user has not chosen a provider and the repo does not make it obvious,
33	ask before proceeding
34
35	Common options:
36
37	- [Convex Auth](https://docs.convex.dev/auth/convex-auth) - good default when
38	the user wants auth handled directly in Convex
39	- [Clerk](https://docs.convex.dev/auth/clerk) - use when the app already uses
40	Clerk or the user wants Clerk's hosted auth features
41	- [WorkOS AuthKit](https://docs.convex.dev/auth/authkit/) - use when the app
42	already uses WorkOS or the user wants AuthKit specifically
43	- [Auth0](https://docs.convex.dev/auth/auth0) - use when the app already uses
44	Auth0
45	- Custom JWT provider - use when integrating an existing auth system not covered
46	above
47
48	Look for signals in the repo before asking:
49
50	- Dependencies such as `@clerk/`, `@workos-inc/`, `@auth0/*`, or Convex Auth
51	packages
52	- Existing files such as `convex/auth.config.ts`, auth middleware, provider
53	wrappers, or login components
54	- Environment variables that clearly point at a provider
55
56	## After Choosing a Provider
57
58	Read the provider's official guide and the matching local reference file:
59
60	- Convex Auth: [official docs](https://docs.convex.dev/auth/convex-auth), then
61	`references/convex-auth.md`
62	- Clerk: [official docs](https://docs.convex.dev/auth/clerk), then
63	`references/clerk.md`
64	- WorkOS AuthKit: [official docs](https://docs.convex.dev/auth/authkit/), then
65	`references/workos-authkit.md`
66	- Auth0: [official docs](https://docs.convex.dev/auth/auth0), then
67	`references/auth0.md`
68
69	The local reference files contain the concrete workflow, expected files and env
70	vars, gotchas, and validation checks.
71
72	Use those sources for:
73
74	- package installation
75	- client provider wiring
76	- environment variables
77	- `convex/auth.config.ts` setup
78	- login and logout UI patterns
79	- framework-specific setup for React, Vite, or Next.js
80
81	For shared auth behavior, use the official Convex docs as the source of truth:
82
83	- [Auth in Functions](https://docs.convex.dev/auth/functions-auth) for
84	`ctx.auth.getUserIdentity()`
85	- [Storing Users in the Convex Database](https://docs.convex.dev/auth/database-auth)
86	for optional app-level user storage
87	- [Authentication](https://docs.convex.dev/auth) for general auth and
88	authorization guidance
89	- [Convex Auth Authorization](https://labs.convex.dev/auth/authz) when the
90	provider is Convex Auth
91
92	Prefer official docs over recalled steps, because provider CLIs and Convex Auth
93	internals change between versions. Inventing setup from memory risks outdated
94	patterns. For third-party providers, only add app-level user storage if the app
95	actually needs user documents in Convex. Not every app needs a `users` table.
96	For Convex Auth, follow the Convex Auth docs and built-in auth tables rather
97	than adding a parallel `users` table plus `storeUser` flow, because Convex Auth
98	already manages user records internally. After running provider initialization
99	commands, verify generated files and complete the post-init wiring steps the
100	provider reference calls out. Initialization commands rarely finish the entire
101	integration.
102
103	## Core Pattern: Protecting Backend Functions
104
105	The most common auth task is checking identity in Convex functions.
106
107	```ts
108	// Bad: trusting a client-provided userId
109	export const getMyProfile = query({
110	args: { userId: v.id("users") },
111	handler: async (ctx, args) => {
112	return await ctx.db.get(args.userId);
113	},
114	});
115	```
116
117	```ts
118	// Good: verifying identity server-side
119	export const getMyProfile = query({
120	args: {},
121	handler: async (ctx) => {
122	const identity = await ctx.auth.getUserIdentity();
123	if (!identity) throw new Error("Not authenticated");
124
125	return await ctx.db
126	.query("users")
127	.withIndex("by_tokenIdentifier", (q) =>
128	q.eq("tokenIdentifier", identity.tokenIdentifier),
129	)
130	.unique();
131	},
132	});

People who liked this also viewed

6 picks

Type