convex-setup-auth

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

byget-convex· 29 skills

Installs

92k

Stars

Forks

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.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/get-convex/agent-skills" --skill "get-convex/agent-skills/convex-setup-auth"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/get-convex/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/get-convex/agent-skills"` and select the relevant skills, then follow their instructions.

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	});
133	```
134
135	## Workflow
136
137	1. Determine the provider, either by asking the user or inferring from the repo
138	2. Ask whether the user wants local-only setup or production-ready setup now
139	3. Read the matching provider reference file
140	4. Follow the official provider docs for current setup details
141	5. Follow the official Convex docs for shared backend auth behavior, user
142	storage, and authorization patterns
143	6. Only add app-level user storage if the docs and app requirements call for it
144	7. Add authorization checks for ownership, roles, or team access only where the
145	app needs them
146	8. Verify login state, protected queries, environment variables, and production
147	configuration if requested
148
149	If the flow blocks on interactive provider or deployment setup, ask the user
150	explicitly for the exact human step needed, then continue after they complete
151	it. For UI-facing auth flows, offer to validate the real sign-up or sign-in flow
152	after setup is done. If the environment has browser automation tools, you can
153	use them. If it does not, give the user a short manual validation checklist
154	instead.
155
156	## Reference Files
157
158	### Provider References
159
160	- `references/convex-auth.md`
161	- `references/clerk.md`
162	- `references/workos-authkit.md`
163	- `references/auth0.md`
164
165	## Checklist
166
167	- [ ] Chosen the correct auth provider before writing setup code
168	- [ ] Read the relevant provider reference file
169	- [ ] Asked whether the user wants local-only setup or production-ready setup
170	- [ ] Used the official provider docs for provider-specific wiring
171	- [ ] Used the official Convex docs for shared auth behavior and authorization
172	patterns
173	- [ ] Only added app-level user storage if the app actually needs it
174	- [ ] Did not invent a cross-provider `users` table or `storeUser` flow for
175	Convex Auth
176	- [ ] Added authentication checks in protected backend functions
177	- [ ] Added authorization checks where the app actually needs them
178	- [ ] Clear error messages ("Not authenticated", "Unauthorized")
179	- [ ] Client auth provider configured for the chosen provider
180	- [ ] If requested, production auth setup is covered too

6 picks

Type

Run `npx skills use "https://github.com/get-convex/agent-skills" --skill "get-convex/agent-skills/convex-setup-auth"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/get-convex/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/get-convex/agent-skills"` and select the relevant skills, then follow their instructions.

convex-setup-auth

How to install convex-setup-auth?

Related

convex-setup-auth

How to install convex-setup-auth?

Related