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

# GitHub Sign-In

> Create a GitHub OAuth App for KnoxCall sign-in — organization-owned, one authorization callback URL, a generated client secret, and the client ID and secret to paste into Settings → Integrations.

# GitHub Sign-In

Adds a **Continue with GitHub** button to the login page, backed by an OAuth App you own. Read [OAuth Sign-In Methods](/integrations/setup/oauth-sign-in) first — it explains when you need your own app (self-hosted deployments do; KnoxCall Cloud does not) and which scope to save under.

**Before you start**

* Owner access to the GitHub **organization** that should own the app. You *can* create the app under a personal account, but an app owned by a person dies with that person's account.
* The **Authorized redirect URI** from the KnoxCall card — **Settings → Integrations → OAuth Sign-In Methods → GitHub**. Self-hosted: set `GITHUB_OAUTH_REDIRECT_URI` first, as described [here](/integrations/setup/oauth-sign-in#self-hosted-set-the-redirect-uri-in-the-server-environment).

## 1. Create the OAuth App

Use an **OAuth App**, not a GitHub App: sign-in is the OAuth web flow, and a GitHub App adds installation and permission machinery KnoxCall does not use.

1. Organization → **Settings → Developer settings → OAuth Apps → New OAuth App**. (For a personal account: your profile → **Settings → Developer settings**.)
2. **Application name**: for example `KnoxCall`. **Homepage URL**: your KnoxCall URL.
3. **Authorization callback URL**: the value from the KnoxCall card:
   * KnoxCall Cloud: `https://auth.knoxcall.com/callback`
   * Self-hosted: `https://<your host>/auth/github/callback` (the value of `GITHUB_OAUTH_REDIRECT_URI`)
4. Leave **Enable Device Flow** off. **Register application**.
5. On the app page copy the **Client ID**, then **Generate a new client secret** and copy it — GitHub shows it once.

## 2. Enter it in KnoxCall

**Settings → Integrations** → scope → **OAuth Sign-In Methods** → **GitHub** tab:

| Field                       | Value                                                                     |
| --------------------------- | ------------------------------------------------------------------------- |
| **Authorized redirect URI** | Read-only. The value you registered in step 1.                            |
| **Client ID**               | The app's Client ID.                                                      |
| **Client secret**           | The generated secret. Leave blank on a later edit to keep the stored one. |

**Save.**

## 3. Verify

Open the login page in a private window and click **Continue with GitHub**. GitHub asks the person to authorise the app for `read:user` and `user:email`; a first-time account is linked to an existing KnoxCall account with the same verified email, or created.

## Things that bite

* **Exactly one callback URL per OAuth App.** Unlike Google, a GitHub OAuth App cannot hold both a staging and a production callback. Create one app per KnoxCall environment.
* **Verified email required.** KnoxCall reads the person's email through `user:email` and only accepts a **verified** address. A GitHub account whose addresses are all unverified is refused with `error=unverified_email`; a private email is fine — the scope reads it even when it is hidden from the public profile.
* **Organization-owned apps and third-party access restrictions.** If the organization restricts third-party OAuth access, an app owned by *that* organization is exempt; an app owned by a personal account may be blocked from reading membership, though sign-in itself does not need it.
* **Rotating the secret.** Generating a new client secret does not revoke the old one until you delete it, so you can generate, save in KnoxCall, then delete the old secret with no gap.
* **A stored row wins over environment variables.** Deleting the row on a self-hosted host that still carries `GITHUB_OAUTH_CLIENT_ID` / `_SECRET` falls back to those.

## Related

* [OAuth Sign-In Methods](/integrations/setup/oauth-sign-in) — scopes, account matching, environment variables, troubleshooting
* [Google](/integrations/setup/oauth-google) · [Microsoft Entra ID](/integrations/setup/oauth-microsoft)