Authentication Setup Guide

Complete guide for setting up all authentication methods in TinyKit Pro.

Overview

TinyKit Pro supports multiple authentication methods:

• Email/Password authentication - Traditional username/password with JWT tokens
• Magic link (email-based) authentication - Passwordless email links
• OAuth providers - GitHub, Google, Apple

Prerequisites

Before setting up authentication, ensure you have:

1. A Convex project with environment variable access
2. A Resend account for email functionality (required for password reset and magic links)
3. OAuth app credentials for any providers you want to enable

Step 1: Configure Better Auth Secret

Better Auth requires a secret key for signing tokens.

Generate Secret

Run this command to generate a secure secret:

openssl rand -base64 32

Add Secret to Convex

Option A: Via Dashboard

1. Go to https://dashboard.convex.dev
2. Navigate to your project's Settings > Environment Variables
3. Add BETTER_AUTH_SECRET with the generated value
4. Add SITE_URL with your site URL (e.g., http://localhost:3000 for development)

Option B: Via CLI

npx convex env set BETTER_AUTH_SECRET <your-generated-secret>
npx convex env set SITE_URL http://localhost:3000

Both approaches are equivalent - use whichever you prefer.

Step 2: Configure Email Services

Email functionality (password reset, magic links) requires RESEND_API_KEY in the Convex environment:

# Add to Convex environment
npx convex env set RESEND_API_KEY re_your_api_key_here

Note: RESEND_API_KEY is set in Convex environment only—not in .env.local. Both auth emails and notification emails use the Convex backend.

Email configuration (support email, domain, site name) is managed via Admin Panel → Site Settings → Email Configuration.

See Environment Variables Reference for complete configuration.

Step 3: Configure OAuth Providers (Optional)

Authentication providers are automatically enabled when their credentials are set in Convex environment variables. No frontend configuration is needed.

GitHub OAuth

1. Create a GitHub OAuth App at https://github.com/settings/applications/new
2. Set callback URL: https://[your-deployment].convex.site/api/auth/callback/github
3. Add to Convex environment variables:

   npx convex env set GITHUB_CLIENT_ID your_github_client_id
   npx convex env set GITHUB_CLIENT_SECRET your_github_client_secret

Google OAuth

1. Create OAuth 2.0 credentials in Google Cloud Console
2. Set authorized redirect URI: https://[your-deployment].convex.site/api/auth/callback/google
3. Add to Convex environment variables:

   npx convex env set GOOGLE_CLIENT_ID your_google_client_id
   npx convex env set GOOGLE_CLIENT_SECRET your_google_client_secret

Apple OAuth

1. Create an Apple Sign In service
2. Configure redirect URL: https://[your-deployment].convex.site/api/auth/callback/apple
3. Add to Convex environment variables:

   npx convex env set AUTH_APPLE_ID your_apple_service_id
   npx convex env set AUTH_APPLE_SECRET your_apple_private_key

Step 4: Testing Authentication

Start Development Server

bun dev

Test Authentication Methods

Navigate to http://localhost:3000/auth/sign-in and test each enabled method:

1. Password Authentication

   • Use the sign-up page to create an account
   • Sign in with email/password

2. Magic Link

   • Enter your email to receive a sign-in link
   • Click the link to authenticate

3. OAuth Providers

   • Click the provider button to authenticate
   • Complete OAuth flow

Password Requirements

When password authentication is enabled, passwords must meet these requirements:

• At least 8 characters long
• Contains at least one uppercase letter
• Contains at least one lowercase letter
• Contains at least one number

Authentication Routes

• Sign In: /auth/sign-in
• Sign Up: /auth/sign-up (only available when password auth is enabled)
• Password Reset: /auth/reset-password

Troubleshooting

"Missing environment variables" error

• Ensure all required environment variables are set in both .env.local and Convex dashboard
• For Better Auth, BETTER_AUTH_SECRET must be set in Convex dashboard

OAuth redirect errors

• Verify callback URLs match exactly in both provider settings and Convex configuration
• Check that OAuth client ID and secret are correctly set in Convex environment variables

Magic link not sending

• Verify RESEND_API_KEY is set in Convex environment variables
• Check Resend dashboard for API key status and sending limits

Password reset emails not working

• Verify all required configuration:
  • RESEND_API_KEY: Valid Resend API key in Convex environment (npx convex env set RESEND_API_KEY re_...)
  • Email settings configured in admin panel ("Site Settings → Email Configuration")
  • Check: Support Email, Support Email Name, Resend Domain, Site URL

Security Notes

• Never commit .env.local or any file containing secrets to version control
• Keep BETTER_AUTH_SECRET secure - it's used to sign authentication tokens
• Regularly rotate OAuth client secrets and API keys
• Use strong password requirements in production environments

← Back to Guides | Authentication Features →