Migrating OAuth apps to Apps

Learn about the advantages of migrating your OAuth app to a App, and learn how to migrate your OAuth app.

In this article

Benefits of migrating from OAuth apps to Apps

Apps are the recommended way to integrate with . Apps offer many advantages over OAuth apps, including:

  • Enhanced security features, like fine-grained permissions, choice over repository access, and short lived tokens
  • The ability to act independently of or on behalf of a user
  • Scalable rate limits
  • Built-in webhooks

For more information, see About creating Apps.

Converting an OAuth app to a App

The following steps provide an overview of how to migrate from an OAuth app to a App. The specific steps depend on your app.

1. Review your OAuth app

Re-familiarize yourself with the code for your OAuth app. The API requests that your OAuth app makes will help you decide what permissions to select for your App.

Additionally, there are a few REST API endpoints that are not available for OAuth apps. Verify that any REST endpoints that you use are available for Apps by reviewing Endpoints available for App installation access tokens.

2. Register a App

Register a new App. For more information, see Registering a App.

Compared to an OAuth app, you have more control over App settings. Some key additions are:

  • Unlike an OAuth app, which always acts on behalf of a user, you can make your App take actions as itself or on behalf of a user. If you do not want your new App to take actions on behalf of a user, you can skip the "Identifying and authorizing users" settings. For more information, see About authentication with a App.

  • You can use webhooks to notify your App when specific events occur. Unlike webhooks for OAuth apps, which you must configure via the API for each repository or organization, webhooks are built into Apps. When you register your App, you can select the webhook events that you want to receive. Additionally, if your OAuth app currently uses polling to determine if an event had occurred, consider subscribing to webhooks instead to help your App stay within the rate limit. For more information, see Using webhooks with Apps.

  • With an OAuth app, you request scopes when a user authorizes your app. With a App, you specify permissions in the app settings. These permissions are more granular than scopes and enable you to only select the permissions that your app needs. Additionally, these permissions are mapped to REST API endpoints and webhook events, so you can easily determine what permissions your App needs in order to access a specific REST API endpoint or subscribe to a specific webhook. Permissions are not currently documented for GraphQL requests. For more information, see Choosing permissions for a App.

3. Modify the code for your app

Once you have registered a App, adapt the code from your old OAuth app to work with your new App.

Update authentication

You will need to update your app's code to handle API authentication for your App. A App can authenticate in three ways:

If you are using 's official Octokit.js library, you can use the built-in App object to authenticate. For examples, see Scripting with the REST API and JavaScript and Building a App that responds to webhook events.

Review rate limits

Review the differences in rate limits between OAuth apps and Apps. Apps use sliding rules for rate limits, which can increase based on the number of repositories and number of users in the organization. For more information, see Rate limits for Apps.

If possible, consider using conditional requests and subscribing to webhooks instead of polling to help you stay within rate limits. For more information about conditional requests, see Best practices for using the REST API. For more information about using webhooks with your App, see Using webhooks with Apps and Building a App that responds to webhook events.

Test your code

Test your new App to make sure that your code works as expected.

4. Publicize your new App

If you want other accounts to be able to use your new App, make sure that your app is public. If you want to make your App more discoverable, list your app in Marketplace. For more information, see About Marketplace for apps and Making a App public or private.

5. Instruct your users to migrate

Once your new App is ready, instruct users of your old OAuth app to migrate to your new App. There is not a way to automatically migrate your users. Each user must install and/or authorize your App on their own.

As the app owner, you should include calls to action to encourage your users to install/authorize the new App and revoke authorization for the old OAuth app. You should also update any documentation or user interface elements.

Prompt users to install your App

If you want your App to make API requests on behalf of itself or access organization or repository resources, the user must install your App. When a user installs a App on their account or organization, they choose which repositories the app can access, and they grant the app the organization and repository permissions that it requested.

To help your users install your App, you can add a link to your app's webpage that users can click to install the App. The format of the install URL is https://.com/apps/YOUR_APP_NAME/installations/new. Replace YOUR_APP_NAME with the sluggified name of your App, which you can find in the "Public link" field on the settings page for your App.

To pre-select any repositories your OAuth app had access to, you can append /permissions and query parameters to the install URL. This helps users grant your App access to repositories that your OAuth app already has access to. The query parameters are:

  • suggested_target_id: The ID of the user or organization that is installing your App. This parameter is required.
  • repository_ids[]: The repository IDs to select for the installation. If omitted, all repositories are selected. The maximum number of repositories that can be pre-selected is 100. To get a list of repositories that your OAuth app has access to, use the List repositories for the authenticated user and List organization repositories endpoints.

For example: https://.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID.

For more information about installing Apps, see Installing a App from Marketplace for your personal account, Installing a App from Marketplace for your organizations, Installing a App from a third party and Installing your own App.

Prompt users to authorize your app

If you want your App to make API requests on behalf of a user, the user must authorize the app. When a user authorizes an app, they grant the app permission to act on their behalf, and they grant the account permissions that the app requested. If the app is installed on an organization account, each user within that organization must authorize the app in order for the app to act on their behalf.

To prompt users to authorize your app, you will lead them through the web application flow or device flow. For more information, see Generating a user access token for a App.

For more information about authorizing Apps, see Authorizing Apps.

Encourage your users to revoke OAuth app access

You should also encourage your users to revoke access for your old OAuth app. This will help you fully transition away from your OAuth app and will help keep your users' data secure. For more information, see Reviewing your authorized OAuth apps.

Update any interfaces or documentation

You should update any user interface or documentation related to your app to reflect the change from an OAuth app to App.

6. Remove webhooks for your old OAuth app

When a user installs your App and grants access to a repository, you should remove any webhooks for your old OAuth app. If your new App and your old OAuth app respond to webhooks for the same event, the user may observe duplicate behavior.

To remove repository webhooks, you can listen for the installation_repositories webhook with the added action. When your App receives that event, you can use the REST API to delete the webhook on those repositories for your OAuth app. For more information, see Webhook events and payloads and REST API endpoints for repository webhooks.

Similarly, to remove organization webhooks, you can listen for the installation webhook with the created action. When your App receives that event for an organization, you can use the REST API to delete the webhook on that organization and corresponding repositories for your OAuth app. For more information, see Webhook events and payloads, REST API endpoints for organization webhooks, and REST API endpoints for repository webhooks.

7. Delete your old OAuth app

Once your users have migrated to your new App, you should delete your old OAuth app. This will help avoid abuse of the OAuth app's credentials. This action will also revoke all of the OAuth app's remaining authorizations. For more information, see Deleting an OAuth app. If your OAuth app is listed on Marketplace, you may need to contact Support to remove your app from the marketplace first.