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.
On this page 9 sections
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:3000by 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. 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.
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:
vibiz auth --devTo view your production configuration and live callback URL, run the command with a full-access key:
vibiz authThe 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:
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:
- Application name: Your app's display name (for example, "Acme Dev" or "Acme Production").
- Homepage URL:
http://localhost:3000for development, or your live domain (such ashttps://app.example.com) for production. - Authorization callback URL: The exact
callback_urldisplayed byvibiz authin 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:
vibiz auth providers add github --own --client-id Iv1.1234567890abcdef --devThe 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:
vibiz auth providers add github --own --client-id Iv1.productionClientIdIf 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.
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:
vibiz init acme-app --template nextjs-saasThe 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.
To run an existing app, install the client package and load the environment at startup:
npm install --save-exact @vibiz/app@0.3.15When your server boots, initialize the environment variables:
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:
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.
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:
vibiz domains add app.example.com --elsewhereIf you are using a Limited key, add the verification TXT record indicated by the CLI (trust_record), then verify it:
vibiz domains verify app.example.comOnce 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.
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:
vibiz auth domains acme.com,partner.com --devTo clear domain restrictions and allow any public GitHub user to register:
vibiz auth domains none --devTo learn more about domain validation behavior, read Restrict sign-up to your company's 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.