# Add GitHub sign-in to your app

> Learn how to add GitHub sign-in to your application using thelastapi, from configuring your GitHub OAuth app to handling sessions in code.

**To add GitHub sign-in to your app, create an OAuth app on GitHub, find your project's callback URL in your sign-in settings, and add your client ID and client secret using the CLI or console.** Every project with authentication enabled receives its own isolated user database and session management. Once you supply your credentials, your application can authenticate users locally on localhost and in production without extra identity infrastructure.

Here is how GitHub authentication works across environments, how to register your OAuth credentials, and how to verify sessions in your application.

## How GitHub sign-in works with thelastapi

When you enable authentication on your project, thelastapi configures a dedicated sign-in service backed by the project's Postgres database. Adding the `auth` resource automatically adds the `database` resource to hold your users, profiles, and sessions. 

The platform supports two social sign-in providers: Google and GitHub. While Google allows the use of shared platform keys so you can test without an OAuth application, GitHub always requires your own `client_id` and `client_secret`. 

Every project maintains two completely separate environments:

- **Development:** Stores local test users in a separate database branch. It trusts `http://localhost:3000` by default so you can test sign-in flows on your machine without altering production data.
- **Production:** Stores live users in your primary database and only trusts your verified production domains.

To learn more about the underlying authentication resource, review the [Sign-in documentation](https://thelastapi.dev/docs/sign-in). If you want an option that skips creating an OAuth application altogether, see how to [Add Google sign-in to your app without your own OAuth app](https://thelastapi.dev/blog/add-google-sign-in).

## Step 1: Find your OAuth callback URL

GitHub requires an Authorization callback URL when registering an application. Because development and production run on separate endpoints, each environment has its own callback URL.

To view your development configuration and find your development callback URL, run:

```bash
vibiz auth --dev
```

To view your production configuration and live callback URL, run the command with a full-access key:

```bash
vibiz auth
```

The CLI prints the current settings as JSON, including the `callback_url` for GitHub and a list of instructions under `available_providers`. You can also retrieve these values over HTTP:

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

Keep your terminal open or copy the callback URL for the environment you are configuring.

## Step 2: Register an OAuth app on GitHub

Open your GitHub account settings, navigate to Developer settings, and select OAuth Apps. Create a new OAuth application with the following fields:

1. **Application name:** Your app's display name (for example, "Acme Dev" or "Acme Production").
2. **Homepage URL:** `http://localhost:3000` for development, or your live domain (such as `https://app.example.com`) for production.
3. **Authorization callback URL:** The exact `callback_url` displayed by `vibiz auth` in Step 1.

Once registered, GitHub displays your **Client ID**. Generate a new **Client Secret** and copy both values.

## Step 3: Add your GitHub credentials to thelastapi

Store your GitHub credentials in your project's authentication settings. Secrets are write-only: they are never displayed in CLI output or API responses, which only return boolean flags like `has_client_secret`.

### For local development

Run the following command to configure GitHub sign-in for your local environment:

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

The CLI prompts you securely for the client secret, or reads it automatically if `GITHUB_CLIENT_SECRET` is set in your current shell environment.

### For production

Production configuration requires a full-access account key. Run the command without the `--dev` flag:

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

If an automated tool or agent using a Limited key attempts to update production authentication settings, the request returns `403 forbidden` with an `owner_only` error reason. For security, production OAuth credentials and SMTP passwords must be entered by an account owner through a full-access CLI session or in the web console. For more details on role boundaries, see the [Keys and environments guide](https://thelastapi.dev/docs/keys).

## Step 4: Wire sign-in into your code

If you are starting fresh, initialize a new project using the pre-wired Next.js SaaS starter:

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

The template includes complete route handlers under `/api/auth/*` and server utilities in `lib/auth/server.ts`. For an end-to-end walkthrough of building with this stack, read [How to add sign-in to a Next.js app](https://thelastapi.dev/blog/add-sign-in-nextjs-app).

To run an existing app, install the client package and load the environment at startup:

```bash
npm install --save-exact @vibiz/app@0.3.15
```

When your server boots, initialize the environment variables:

```ts
import { vibiz } from '@vibiz/app';

// Injects VIBIZ_AUTH_* and DATABASE_URL into process.env
await vibiz.loadEnv();
```

When you run `vibiz dev`, the CLI populates `.env.development.local` with the variables needed to communicate with your sign-in service:

| Environment variable | Purpose |
| --- | --- |
| `VIBIZ_AUTH_BASE_URL` | The authentication endpoint for the active environment |
| `VIBIZ_AUTH_COOKIE_SECRET` | Secret key used to encrypt and sign session cookies |
| `VIBIZ_AUTH_JWKS_URL` | Endpoint to verify JWT tokens manually if needed |
| `VIBIZ_AUTH_PROJECT_ID` | Your unique project identifier |

In your server components or API routes, you can verify who is signed in:

```ts
import { currentUser } from '@/lib/auth/server';

export default async function DashboardPage() {
  const user = await currentUser();

  if (!user) {
    return <p>Please sign in with GitHub to view this page.</p>;
  }

  return (
    <div>
      <h1>Welcome back</h1>
      <p>Signed in as {user.email}</p>
    </div>
  );
}
```

If you are deploying your frontend on infrastructure outside thelastapi hosting, you only need to store `VIBIZ_APP_KEY` on your host. Calling `await vibiz.loadEnv()` pulls the correct configuration during boot, as explained in [Use one service](https://thelastapi.dev/docs/use-one).

## Step 5: Trust your live domain

Local development automatically allows `http://localhost:3000`. In production, the authentication service rejects requests from unknown origins to prevent session hijacking.

Before launching, tell thelastapi where your production app is hosted. If you deploy outside thelastapi hosting, register your domain:

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

If you are using a Limited key, add the verification TXT record indicated by the CLI (`trust_record`), then verify it:

```bash
vibiz domains verify app.example.com
```

Once verified (or if confirmed directly by the account owner), the authentication service accepts sign-in redirects and manages sessions on `app.example.com`. Domains bought directly through thelastapi with `vibiz domains buy` are verified and trusted automatically without manual DNS configuration, as documented in the [Domains documentation](https://thelastapi.dev/docs/domains).

## Restricting sign-ups by email domain

By default, any user with a valid GitHub account can sign in to your application. If you are building an internal company tool, you can restrict sign-ups to specific email domains.

To restrict development sign-ups to employees and contractors:

```bash
vibiz auth domains acme.com,partner.com --dev
```

To clear domain restrictions and allow any public GitHub user to register:

```bash
vibiz auth domains none --dev
```

To learn more about domain validation behavior, read [Restrict sign-up to your company's email domain](https://thelastapi.dev/blog/restrict-sign-up-email-domain).

## Sign-in feature comparison

| Feature | Supported | Notes |
| --- | --- | --- |
| GitHub OAuth | Yes | Requires your own OAuth App (`client_id` and `client_secret`) |
| Google OAuth | Yes | Supports shared platform keys or your own OAuth App |
| Email + Password | Yes | Optional email verification via one-time code or link |
| Magic Links | Yes | Expiration configurable between 5 and 1440 minutes |
| Allowed Email Domains | Yes | Up to 50 domains allowed per project |
| MFA / Two-Factor | No | Not available yet |
| User Banning | No | Not available yet |
| Custom Session Lifetimes | No | Uses platform default session duration |

To get started, create a project with `vibiz init <project-name>`, configure your GitHub OAuth keys in your development environment, and run `vibiz dev` to test your sign-in flow locally.

## Frequently asked questions

### Why can't I use shared platform keys for GitHub sign-in like I can for Google?

GitHub's OAuth implementation requires each application to register its own distinct credentials and redirect URLs. While the platform provides shared keys for Google sign-in to help you test quickly, GitHub authentication always requires your own `client_id` and `client_secret`.

### Can an AI agent or Limited key update production GitHub credentials?

No. Any attempt by a Limited key to update production authentication settings or add secrets returns a `403 forbidden` error with `details.reason: "owner_only"`. Production secrets must be entered directly by an account owner using a full-access key in the CLI or through the web console.

### How do I remove GitHub sign-in from my project?

You can disable the GitHub provider at any time by running `vibiz auth providers rm github --dev` for your development environment, or `vibiz auth providers rm github` with a full-access key for your production environment.

### What happens if an unauthorized user attempts to sign up when email domains are restricted?

If you configure allowed email domains using `vibiz auth domains`, any GitHub user whose primary verified email does not match the allowed domain list is rejected during the authentication callback and denied an active session.

---

Published 2026-11-15 · https://thelastapi.dev/blog/add-github-sign-in
