APIs & Integrations
GitHub App OAuth
Overview
Pre-built tooling
Pre-built integrations
Not seeing the integration you need? Build your own independently.
Access requirements
| Pre-Requisites | Status | Comment |
|---|---|---|
| Paid dev account | ✅ Not required | Free, self-signup for a GitHub account. |
| 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
1
Create a GitHub account
If you don’t already have one, sign up for a GitHub account.
2
Create a new OAuth App
- In the upper-right corner of any GitHub page, click your profile photo, then click Settings.
- Scroll down and click Developer settings.
- In the left sidebar, click OAuth Apps.
- Click New OAuth App.
3
Register your app
- Under Application name, enter a name for your app. Choose a clear and short name (maximum 34 characters).
- 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.
- Optionally, under Description, type a description of your app. Users will see this when installing your app.
- Authorization callback URL: Enter
https://api.nango.dev/oauth/callback.
4
Save your Client ID and Client Secret
After registration:
- Note your Client ID (visible).
- Click Generate a new client secret to reveal your Client Secret.
- Store both securely; you’ll need them in Nango.
5
Creating a GitHub App
If you don’t already have a GitHub App, please follow the steps to create one.
6
Next
Follow the Quickstart.
Need help getting started? Get help in the community.
Contribute improvements to the setup guide by editing this page
Useful links
Contribute useful links by editing this page
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)
- 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 and the checkbox “Request user authorization (OAuth) during installation” should be checked
- The checkbox “Redirect on update” under “Post installation” should NOT be checked and the “Setup URL (optional)” should not be accessible
- The GitHub App OAuth flow is a hybrid between a GitHub App and an OAuth App. It is recommended when your GitHub App needs approval before being installed into an organization.
- 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. 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.
- GitHub App OAuth authentication uses a user access token, rather than an installation token.
- Webhook payloads are signed with the webhook secret you configured. Always verify the signature to ensure the webhook is legitimate.
Contribute API gotchas by editing this page