GitHub sign-in

This guide walks through Sign in with GitHub end-to-end: turning it on in the SimpleAuth dashboard, optionally bringing your own GitHub OAuth App, and adding a button in your frontend.

Part 1 — Enable in the dashboard

1. Sign in to SimpleAuth and open your app.
2. Go to Settings.
3. Turn Enable GitHub sign-in on.
4. Choose Shared (fastest) for local development (uses the server’s GITHUB_OAUTH_SHARED_* env vars), or Your GitHub credentials for production.
5. Under Allowed redirect origins, add one origin per line, e.g. https://myapp.com and http://localhost:3000. These must match the origin of the redirectUrl you pass from your app (path can differ; origin must match). In development, http://localhost / 127.0.0.1 on any port is allowed even if omitted.
6. Click Save.

Part 2 — Bring your own GitHub OAuth App (BYO)

1. Go to GitHub → Settings → Developer settings → OAuth Apps (or your org’s developer settings).
2. Click New OAuth App.
3. Set Application name, Homepage URL (your product URL), and Authorization callback URL to the exact callback URL for the SimpleAuth API host, e.g.
   https://simpleauth.net/api/external/auth/oauth/github/callback
   When developing against a local SimpleAuth server, use http://localhost:3000/api/external/auth/oauth/github/callback instead.
4. Click Register application, then copy the Client ID and generate a Client secret (copy it once — GitHub may not show it again).
5. In SimpleAuth Settings → GitHub sign-in, select Your GitHub credentials, paste Client ID, paste Client Secret (first time), set Allowed redirect origins, and Save.

Part 3 — Frontend (React CLI + button)

1. Install the JS SDK in your app: npm install @simpleauthjs/core
2. Add the GitHub feature (if you did not use the basic preset which already includes it):

npx @simpleauthjs/react add github-auth

3. Pass a post-login URL into your sign-in UI (same origin must be allowlisted):

<SignInForm githubRedirectUrl="https://myapp.com/dashboard" />

or use the button directly:

import { GithubButton } from "@/components/simpleauth"

<GithubButton redirectUrl="https://myapp.com/dashboard" />

4. Or call the client from your own button:

import { createSimpleAuthClient } from "@simpleauthjs/core"

const auth = createSimpleAuthClient({ apiKey: "sa_live_…" })
auth.signInWithGithub({ redirectUrl: "https://myapp.com/dashboard" })

Part 4 — Troubleshooting

Webhooks

SimpleAuth may enqueue webhook events such as user.signed_in_via_github, user.registered_via_github, and user.linked_github_account when your app has active webhook endpoints configured.