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

# How to register your own GitHub App OAuth app

> Register an OAuth app with GitHub and connect it to Nango

This guide shows you how to set up a GitHub App with OAuth authorization to obtain your credentials. GitHub App OAuth is a hybrid approach that combines the benefits of both GitHub Apps and OAuth Apps.

## Access requirements

| Pre-Requisites    | Status         | Comment                                                                  |
| ----------------- | -------------- | ------------------------------------------------------------------------ |
| Paid dev account  | ✅ Not required | Free, self-signup for a [GitHub account](https://github.com/signup).     |
| Paid test account | ✅ Not required | Free GitHub account can be used for testing.                             |
| Partnership       | ✅ Not required |                                                                          |
| App review        | ⚠️ Conditional | Required only if you want to publish your app to the GitHub Marketplace. |
| Security audit    | ✅ Not required |                                                                          |

## Setup guide

<Steps>
  <Step title="Create a GitHub account">
    If you don't already have one, sign up for a [GitHub account](https://github.com/signup).
  </Step>

  <Step title="Create a new OAuth App">
    1. In the upper-right corner of any GitHub page, click your profile photo, then click **Settings**.
    2. Scroll down and click **Developer settings**.
    3. In the left sidebar, click **OAuth Apps**.
    4. Click **New OAuth App**.
  </Step>

  <Step title="Register your app">
    1. Under **Application name**, enter a name for your app. Choose a clear and short name (maximum 34 characters).
    2. Under **Homepage URL**, type the full URL to your app's website. If you don't have a dedicated URL, you can use your GitHub repository URL or organization URL.
    3. Optionally, under **Description**, type a description of your app. Users will see this when installing your app.
    4. **Authorization callback URL**: Enter `https://api.nango.dev/oauth/callback`.
  </Step>

  <Step title="Save your Client ID and Client Secret">
    After registration:

    1. Note your **Client ID** (visible).
    2. Click **Generate a new client secret** to reveal your **Client Secret**.
    3. Store both securely; you'll need them in Nango.
  </Step>

  <Step title="Creating a GitHub App">
    If you don't already have a GitHub App, please follow the [steps](/api-integrations/github-app#setup-guide) to create one.
  </Step>

  <Step title="Next">
    Follow the [*Quickstart*](/getting-started/quickstart).
  </Step>
</Steps>

<Tip>Need help getting started? Get help in the [community](https://nango.dev/slack).</Tip>

<Note>Contribute improvements to the setup guide by [editing this page](https://github.com/nangohq/nango/tree/master/docs/api-integrations/github-app-oauth.mdx)</Note>

## Understanding the GitHub App OAuth Flow

The GitHub App OAuth flow is a **hybrid between a GitHub App and a traditional OAuth App**.

It enables authentication of:

* ✅ **The user**, via OAuth authorization
* ✅ **The installation**, via app tokens

### Why use it?

This flow is recommended when your GitHub App:

* Requires **user identity and permissions**
* Needs to be **approved before installation** into an organization

### Key Differences Between Installation & Authorization

* 🧩 **Installation Tokens** (installation-based access):
  * Created by the app backend using a JWT and installation ID
  * Not tied to any specific user
  * Short-lived (1 hour), scoped to the org/repo permissions granted at install time
  * Used for server-side GitHub API operations like issues, PRs, branches, and checks
  * ⚠️ Cannot access user-specific data (like profile, personal repos)
  * ✅ A single installation token can be used across all users within the same GitHub App installation

* 👤 **OAuth User Tokens** (user-based access):
  * Obtained when a user authorizes the app via the OAuth flow
  * Used to fetch user-specific resources, such as their GitHub profile or private personal repositories
  * ⚠️ These cannot access private organization repositories unless the app is also installed in that org

### Best Practices

* 🔐 Use **installation tokens** for all organization/repo-level operations
* 🙋 Use **OAuth tokens** when you need to personalize the user experience (e.g., show GitHub avatar or access user-specific data)
* ✅ Installation tokens are **shared across users** in the same installation and do not need to be regenerated per user

## API gotchas

* When setting up a GitHub App OAuth:
  * The App ID is made of numbers (e.g. 401953)
  * The App Public Link is the URL to your Github App public page (e.g. [https://github.com/apps/nango-github-app](https://github.com/apps/nango-github-app))
  * The App Private Key needs to be generated in your GitHub App settings and starts with `-----BEGIN RSA PRIVATE KEY-----` (not to be confused with the Client Secrets)
  * The "Callback URL" needs to be filled in with the callback URL which unless customized will be [https://api.nango.dev/oauth/callback](https://api.nango.dev/oauth/callback) and the checkbox "Request user authorization (OAuth) during installation" should be checked
  * The checkbox "Redirect on update" under "Post installation" should be checked and the "Setup URL (optional)" should not be accessible
* There are certain API methods that only work with an OAuth App that will not work with an App. Please check the Github documentation and look for a "Works with Github Apps" header under the endpoint.
* Nango supports initiating a connection with a GitHub App using the frontend SDK, but not directly from the [GitHub Marketplace](https://github.com/marketplace). Therefore, you should encourage users to install your GitHub App from your product, rather than from the GitHub Marketplace directly. This is a limitation we plan to fix in the future.
* Just like GitHub Apps, OAuth Apps can access GitHub's REST and GraphQL APIs, though the endpoints they can use are limited by the OAuth scopes granted by the user during authorization.
* Webhook payloads are signed with the webhook secret you configured. Always verify the signature to ensure the webhook is legitimate.

For more information, see the [GitHub Apps documentation](https://docs.github.com/en/apps) and [differences between GitHub Apps and OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps).

***