# OAuth callback URLs explained

> An OAuth callback URL is the endpoint in your application where an identity provider redirects users with an authorization code after they sign in.

**An OAuth callback URL, also known as a redirect URI, is the exact web address where an identity provider redirects a user after they approve a sign-in request.** When a user authenticates with an external service, that service sends the browser back to this address along with a temporary authorization code or an error parameter. Your server exchanges that code for identity tokens to authenticate the user and start their session.

If the URL in the sign-in request does not match the callback URL registered in the provider's developer console down to the scheme, port, and trailing slash, the sign-in attempt fails immediately. Understanding how callback URLs work helps you prevent redirect URI errors and keep development and production environments properly isolated.

## How the OAuth callback flow works

When you add social sign-in to an application, your code delegates credential handling to an external identity provider such as Google or GitHub. The callback URL is the return address that ties the entire flow together.

The exchange happens in four steps:

1. **Initiation:** The user clicks a sign-in button. Your app sends them to the provider's authorization screen. This request includes your client identifier, requested scopes, and a `redirect_uri` parameter pointing to your app's callback handler.
2. **User consent:** The identity provider prompts the user to verify their account and grant permission.
3. **Redirect:** The identity provider redirects the user's browser back to the callback URL specified in step one. The URL contains query parameters such as `?code=auth_code_here&state=xyz`.
4. **Token exchange:** Your application receives the request, extracts the authorization code, and sends it directly from your server to the provider's token endpoint. The provider returns identity data and access tokens. Your app sets a secure session cookie and displays the authenticated view.

```
+-------------+         1. Sign-in redirect (with callback URL)         +-------------------+
|             | ------------------------------------------------------> |                   |
|             |                                                         | Identity Provider |
|             |         3. Browser redirected to callback URL           |  (Google, GitHub) |
|   Browser   | <------------------------------------------------------ |                   |
|             |            (?code=abc123xyz&state=state_val)            +-------------------+
|             |                                                                   ^
|             | 4. Load authenticated app                                         | 4. Server-to-server
v             v                                                                   |    token exchange
+-----------------------------------------------------------------------+         |
|                          Your Web Application                         | <-------+
|  Callback endpoint: https://app.example.com/api/auth/callback/google   |
+-----------------------------------------------------------------------+
```

Because identity providers only redirect to destinations you have registered ahead of time, an attacker cannot intercept authorization codes by tampering with the `redirect_uri` parameter on the initial request.

## Why exact string matching causes redirect URI errors

The most common failure in social authentication is the `redirect_uri_mismatch` error. Identity providers do not parse callback URLs leniently; they perform an exact string comparison against the authorized redirect URIs entered in your project settings.

A discrepancy between what your application requests and what the provider expects triggers a failure before the user can even enter credentials. Common mismatches include:

- **Protocol differences:** Registering `https://` while your local dev server runs over `http://`.
- **Port numbers:** Forgetting the port in local testing, such as using `localhost` instead of `localhost:3000`.
- **Domain variations:** Supplying `example.com` when the browser sends requests to `www.example.com`.
- **Path typos:** Missing a subpath or trailing slash, such as `/api/auth/callback/google/` versus `/api/auth/callback/google`.

When troubleshooting a redirect URI mismatch, look at the failed URL in your browser's address bar. The identity provider will often include the requested `redirect_uri` in the query parameters of its error screen. Compare that raw value character-by-character with the URL listed in the developer console.

## Handling callbacks in development versus production

Managing OAuth callback URLs requires maintaining separate configurations for local development and live deployments. A development environment runs on a local loopback address, while a production deployment runs on a public domain protected by TLS.

Never add `http://localhost` callback URLs to your production OAuth credentials. Doing so creates a security vulnerability where an attacker could exploit local redirect handlers.

In thelastapi, the `auth` resource isolates environments automatically. Every project has two environments, each with its own database and authentication setup:

- **Development:** Trust is scoped exclusively to `http://localhost:3000`. The development sign-in service accepts local redirects so you can build on your laptop without configuring custom domains.
- **Production:** Localhost is disabled by default. The production sign-in service only trusts domains associated with your live project.

You can inspect the exact callback URLs configured for each environment using the CLI:

```bash
# View the production sign-in settings and callback URLs
vibiz auth

# View the development copy settings and callback URLs
vibiz auth --dev
```

You can also fetch sign-in configuration over HTTP using the project settings endpoint:

```bash
curl "https://thelastapi.dev/v1/projects/prj_123/auth/settings?env=development" \
  -H "Authorization: Bearer $VIBIZ_API_KEY"
```

The returned JSON includes the `callback_url` for each provider in that environment, along with provider-specific setup steps under `available_providers`.

## Configuring OAuth providers and callbacks

Depending on the provider, you can either rely on managed authentication infrastructure or supply your own developer credentials.

### Using Google sign-in with shared credentials

For rapid prototyping or production apps that do not require branded OAuth consent screens, you can activate Google sign-in without creating a custom OAuth app in the Google Cloud Console.

```bash
vibiz auth providers add google --dev
```

When using shared credentials, callback URLs and client secrets are handled internally. If you want your application's specific branding, support contact, and logo displayed to users during sign-in, you can switch to your own OAuth credentials. For detailed setup steps, see our guides on [how to add Google sign-in without your own OAuth app](https://thelastapi.dev/blog/add-google-sign-in) and [using your own OAuth app for Google sign-in](https://thelastapi.dev/blog/own-oauth-app-google-sign-in).

### Using GitHub sign-in

GitHub sign-in uses standard OAuth apps configured in GitHub settings. Run the following command to register GitHub authentication for development:

```bash
vibiz auth providers add github --own --client-id Iv1.abc123xyz --dev
```

The CLI will prompt you securely for the client secret, or read it from `GITHUB_CLIENT_SECRET`. Once configured, GitHub redirects sign-in attempts back to the sign-in service callback URL displayed in `vibiz auth --dev`.

### Callback setup comparison

| Provider | Shared credentials supported | Custom credentials supported | Callback URL source |
| --- | --- | --- | --- |
| Google | Yes (`credentials: "shared"`) | Yes (`credentials: "own"`) | `vibiz auth` settings |
| GitHub | No | Yes | `vibiz auth` settings |

## Domain trust and external hosting

When your application is hosted directly on thelastapi hosting, your production domain and its `https://<slug>.vibiz.app` address are trusted automatically.

If you deploy your frontend or backend on another host, you can still use the database, sign-in, AI, and payments without using our hosting. You must register the external domain with your project so the authentication service recognizes it as a valid origin and redirect target. More details are available in the documentation for [using one service on its own](https://thelastapi.dev/docs/use-one).

To connect an external domain:

```bash
vibiz domains add app.example.com --elsewhere
```

- When run with a full-access key, the domain is trusted immediately.
- When run with a Limited key (such as an AI agent running in development), sign-in trusts the address once the required DNS TXT verification record (`trust_record`) is detected by running `vibiz domains verify app.example.com`, or when confirmed manually by the account owner.

If you purchased your domain directly through thelastapi CLI or console (see [Domains documentation](https://thelastapi.dev/docs/domains)), DNS records are managed automatically. Any project on your account can claim the domain or a subdomain using `vibiz domains use example.com`, and the address is instantly trusted for authentication callbacks without manual DNS records.

## Wiring callback handling into your application code

If you generate your project with the SaaS template:

```bash
vibiz init acme-app --template nextjs-saas
```

The starter application includes authentication routes out of the box. In this template, authentication requests flow through the `/api/auth/*` route, and session data is resolved on the server using `currentUser()` in `lib/auth/server.ts`. For a complete walkthrough on configuring these routes, read our tutorial on [how to add sign-in to a Next.js app](https://thelastapi.dev/blog/add-sign-in-nextjs-app).

The application reads its environment configuration from variables injected during boot:

```ts
// lib/auth/server.ts
import { vibiz } from '@vibiz/app';

// Load environment variables automatically at startup
await vibiz.loadEnv();

// The environment provides:
// process.env.VIBIZ_AUTH_BASE_URL
// process.env.VIBIZ_AUTH_COOKIE_SECRET
// process.env.VIBIZ_AUTH_JWKS_URL
// process.env.VIBIZ_AUTH_PROJECT_ID
```

When building locally, run `vibiz dev` to branch your database, provision isolated development authentication settings, and write the appropriate credentials to `.env.development.local`. This ensures your local instance redirects to `http://localhost:3000` while production routes users to your live domain.

For deeper technical details on configuring providers, token expiration, and email domain restrictions, visit the official [Sign-in documentation](https://thelastapi.dev/docs/sign-in) and [Keys and environments guide](https://thelastapi.dev/docs/keys).

## Frequently asked questions

### Why am I getting a redirect_uri_mismatch error during OAuth sign-in?

This error means the callback URL sent in the authorization request does not match the allowed callback URLs registered with the identity provider. Check for subtle differences in protocol (http vs. https), port numbers, subdomains, or missing trailing slashes.

### Can I use localhost as an OAuth callback URL in production?

No, you should never register localhost callback URLs in production OAuth configurations. Keep localhost URLs restricted to separate development credentials to prevent security vulnerabilities and accidental data crossover.

### How do I find the callback URL to paste into the Google or GitHub developer console?

Run `vibiz auth` for your production callback URL or `vibiz auth --dev` for your development URL. The CLI output lists the registered callback URLs for each provider and links directly to their developer console setup steps.

### What happens if an external domain is not verified before handling sign-in callbacks?

The authentication service will reject sign-in requests from unauthorized origins. If hosting outside thelastapi, register the domain with `vibiz domains add <domain> --elsewhere` and verify its TXT record using `vibiz domains verify <domain>` before sending live traffic.

---

Published 2026-11-15 · https://thelastapi.dev/blog/oauth-callback-urls-explained
