Skip to main content

​
Overview

Cat Web requires several environment variables to connect to your Auth0 tenant and backend API. This guide walks you through setting up your configuration.
Never commit your .env file to version control. Ensure .env is listed in your .gitignore file.

​
Required Environment Variables

Cat Web uses Vite’s environment variable system, which requires all variables to be prefixed with VITE_ to be exposed to the client.

​
Environment Variables

Create a .env file in the root of your project with the following variables: 
VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your_client_id
VITE_AUTH0_AUDIENCE=your_api_identifier
VITE_API_BASE_URL=http://localhost:8080
​
VITE_AUTH0_DOMAIN
string
required
Your Auth0 tenant domain (e.g., your-tenant.auth0.com or your-tenant.us.auth0.com)
​
VITE_AUTH0_CLIENT_ID
string
required
The Client ID from your Auth0 Application settings
​
VITE_AUTH0_AUDIENCE
string
required
The API identifier/audience for your Auth0 API
​
VITE_API_BASE_URL
string
required
The base URL for your backend API (e.g., http://localhost:8080 for local development or your production API URL)

​
Auth0 Setup

To obtain the required Auth0 credentials, follow these steps:
1

Create an Auth0 Account

If you don’t have an Auth0 account, sign up at auth0.com.
2

Create a Single Page Application

In your Auth0 Dashboard:
  1. Navigate to Applications > Applications
  2. Click Create Application
  3. Enter a name (e.g., “Cat Web”)
  4. Select Single Page Web Applications
  5. Click Create
3

Configure Application Settings

In your application settings, configure the following:Allowed Callback URLs
http://localhost:5173, https://your-production-domain.com
Allowed Logout URLs
http://localhost:5173, https://your-production-domain.com
Allowed Web Origins
http://localhost:5173, https://your-production-domain.com
Allowed Origins (CORS)
http://localhost:5173, https://your-production-domain.com
Click Save Changes at the bottom of the page.
4

Get Your Credentials

From the application settings page, copy:
  • Domain → VITE_AUTH0_DOMAIN
  • Client ID → VITE_AUTH0_CLIENT_ID
5

Create an API

To get the audience value:
  1. Navigate to Applications > APIs
  2. Click Create API
  3. Enter a name (e.g., “Cat Web API”)
  4. Enter an identifier (e.g., https://api.cat-web.com)
  5. Click Create
  6. Copy the Identifier → VITE_AUTH0_AUDIENCE

​
Environment File Setup

1

Create the .env file

Create a .env file in the root directory of your project:
touch .env
2

Add your credentials

Open the .env file and add your configuration:
# Auth0 Configuration
VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=abc123def456ghi789
VITE_AUTH0_AUDIENCE=https://api.cat-web.com

# API Configuration
VITE_API_BASE_URL=http://localhost:8080
3

Verify .gitignore

Ensure your .gitignore file includes .env:
# Environment variables
.env
.env.local
.env.*.local
After creating or modifying the .env file, restart your development server for changes to take effect.

​
Configuration in Code

​
Auth0 Provider Setup

The Auth0 provider is configured in src/main.tsx: 
import { Auth0Provider } from '@auth0/auth0-react';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <Auth0Provider
      domain={import.meta.env.VITE_AUTH0_DOMAIN}
      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
      authorizationParams={{
        redirect_uri: window.location.origin,
        audience: import.meta.env.VITE_AUTH0_AUDIENCE,
      }}
    >
      <App />
    </Auth0Provider>
  </StrictMode>
)

​
API Service Configuration

The API service uses the VITE_API_BASE_URL environment variable in src/services/api-service.ts: 
export class ApiService {
  static async getPhoneNumbers(getAccessToken: () => Promise<string>) {
    const res = await fetch(
      `${import.meta.env.VITE_API_BASE_URL}/api/phone-numbers`,
      {
        headers: {
          Authorization: `Bearer ${await getAccessToken?.()}`,
        },
      }
    );
    return await res.json();
  }
}

​
Configuration Validation

To verify your configuration is correct:
1

Start the development server

npm run dev
2

Open the application

Navigate to http://localhost:5173 in your browser.
3

Test authentication

Click the login button. You should be redirected to Auth0’s login page.
If you see the Auth0 login page, your configuration is correct.
4

Complete login

After logging in, you should be redirected back to the application and see the dashboard.

​
Troubleshooting

This error indicates that VITE_AUTH0_DOMAIN is not set or is empty.Solution:
  1. Verify your .env file contains VITE_AUTH0_DOMAIN
  2. Restart the development server
  3. Clear your browser cache
This error indicates that VITE_AUTH0_CLIENT_ID is not set or is empty.Solution:
  1. Verify your .env file contains VITE_AUTH0_CLIENT_ID
  2. Ensure you copied the correct Client ID from Auth0
  3. Restart the development server
This error occurs when the callback URL is not configured in Auth0.Solution:
  1. Go to your Auth0 Application settings
  2. Add your application URL to Allowed Callback URLs
  3. Add your application URL to Allowed Web Origins
  4. Save changes and try again
This indicates an issue with the API audience or token.Solution:
  1. Verify VITE_AUTH0_AUDIENCE matches your Auth0 API Identifier
  2. Ensure your backend API is configured to validate tokens from Auth0
  3. Check that VITE_API_BASE_URL points to the correct backend
Vite only exposes variables prefixed with VITE_.Solution:
  1. Ensure all variables start with VITE_
  2. Restart the development server after modifying .env
  3. Clear Vite’s cache: rm -rf node_modules/.vite

​
Production Configuration

For production deployments, set environment variables through your hosting platform: 
vercel env add VITE_AUTH0_DOMAIN
vercel env add VITE_AUTH0_CLIENT_ID
vercel env add VITE_AUTH0_AUDIENCE
vercel env add VITE_API_BASE_URL
Remember to update your Auth0 Application settings with production URLs in Allowed Callback URLs, Allowed Logout URLs, and Allowed Web Origins.

​
Next Steps

With your configuration complete, you’re ready to start using Cat Web!

User Guide

Learn how to use Cat Web’s features

API Reference

Explore the API service methods

Build docs developers (and LLMs) love

Get started for freeTalk to us