> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aspfox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth Configuration

> Set up Google and GitHub OAuth for social login.

<Note>
  OAuth providers are optional. AspFox works without them — email/password and magic link authentication are available regardless. Only the Google and GitHub login buttons require OAuth configuration.
</Note>

## Google OAuth

### Create OAuth credentials

1. Go to [console.cloud.google.com](https://console.cloud.google.com)

2. Create a new project (or select an existing one)

3. Go to **APIs & Services → Credentials**

4. Click **Create Credentials → OAuth 2.0 Client ID**

5. Application type: **Web application**

6. Add authorized redirect URIs:

   **Local development:**

   ```
   http://localhost:5000/api/v1/auth/google/callback
   ```

   **Production:**

   ```
   https://api.yourdomain.com/api/v1/auth/google/callback
   ```

7. Click **Create**

8. Copy the **Client ID** and **Client Secret**

### Add to .env

```bash theme={null}
GOOGLE_CLIENT_ID=123456789-abcdefghijklmnop.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abc123def456ghi789
```

## GitHub OAuth

### Create an OAuth App

1. Go to [github.com/settings/developers](https://github.com/settings/developers)

2. Click **OAuth Apps → New OAuth App**

3. Fill in the form:

   **Local development:**

   * Application name: `Your App (Local)`
   * Homepage URL: `http://localhost:5173`
   * Authorization callback URL: `http://localhost:5000/api/v1/auth/github/callback`

   **Production:**

   * Application name: `Your App`
   * Homepage URL: `https://yourdomain.com`
   * Authorization callback URL: `https://api.yourdomain.com/api/v1/auth/github/callback`

4. Click **Register application**

5. Copy the **Client ID**

6. Click **Generate a new client secret** and copy it

### Add to .env

```bash theme={null}
GITHUB_CLIENT_ID=Iv1.abc123def456
GITHUB_CLIENT_SECRET=abc123def456ghi789jkl012mno345pqr678stu901
```

## Common issues

<Warning>
  OAuth callback URLs must match **exactly**. The protocol (`http` vs `https`), port number, and trailing slash all matter. A mismatch causes a redirect\_uri\_mismatch error from the OAuth provider with no useful error message in the browser.

  If Google OAuth fails with "redirect\_uri\_mismatch":

  1. Check the URL your API is receiving in the callback
  2. Log `context.Request.Query["redirect_uri"]` temporarily
  3. Add that exact URL to the allowed list in Google Cloud Console
</Warning>

**Separate OAuth apps for local and production** — you cannot use the same redirect URI for both `localhost` and a production domain. Create separate credentials for each environment, or add both redirect URIs to the same Google project. GitHub allows multiple redirect URIs per app; Google does too.

**Scope:** AspFox requests only `email` and `profile` scopes from Google, and `user:email` from GitHub. No additional scopes are needed.