Identifying and authorizing users for GitHub Apps

Your GitHub App can perform actions on behalf of a user, like creating an issue, creating a deployment, and using other supported endpoints.

When your GitHub App acts on behalf of a user, it performs user-to-server requests. These requests must be authorized with a user's access token. User-to-server requests include requesting data for a user, like determining which repositories to display to a particular user. These requests also include actions triggered by a user, like running a build.

Note: To access the API with your GitHub App, you must provide a custom media type in the Accept Header for your requests.

application/vnd.github.machine-man-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Enterprise Support.

Identifying users on your site

The flow to identify users on your site is:

  1. Users are redirected to request their GitHub identity
  2. Users are redirected back to your site by GitHub
  3. Your GitHub App accesses the API with the user's access token

1. Request a user's GitHub identity

GET http(s)://[hostname]/login/oauth/authorize

When your GitHub App specifies a login parameter, it prompts users with a specific account they can use for signing in and authorizing your app.

Parameters

Name Type Description
client_id string Required. The OAuth client ID for your GitHub App. You can find this in your GitHub App settings when you select your app.
redirect_uri string The URL in your application where users will be sent after authorization. This must be an exact match to the URL you provided in the User authorization callback URL field when setting up your GitHub App and can't contain any additional parameters.
state string This should contain a random string to protect against forgery attacks and could contain any other arbitrary data.
login string Suggests a specific account to use for signing in and authorizing the app.

Note: You don't need to provide scopes in your authorization request. Unlike traditional OAuth, the authorization token is limited to the permissions associated with your GitHub App and those of the user.

2. Users are redirected back to your site by GitHub

If the user accepts your request, GitHub redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don't match, the request was created by a third party and the process should be aborted.

Exchange this code for an access token:

POST http(s)://[hostname]/login/oauth/access_token

Parameters

Name Type Description
client_id string Required. The OAuth client ID for your GitHub App.
client_secret string Required. The OAuth client secret for your GitHub App.
code string Required. The code you received as a response to Step 1.
redirect_uri string The URL in your application where users are sent after authorization.
state string The unguessable random string you provided in Step 1.

Response

By default, the response takes the following form:

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer

3. Your GitHub App accesses the API with the user's access token

The user's access token allows the GitHub App to make requests to the API on behalf of a user.

Authorization: token OAUTH-TOKEN
GET http(s)://[hostname]/api/v3/user

For example, in curl you can set the Authorization header like this:

curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/user

Check which installation's resources a user can access

Once you have an OAuth token for a user, you can check which installations that user can access.

Authorization: token OAUTH-TOKEN
GET /user/installations

You can also check which repositories are accessible to a user for an installation.

Authorization: token OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

More details can be found in: List installations for a user and List repositories accessible to the user for an installation.

Handling a revoked GitHub App authorization

If a user revokes their authorization of a GitHub App, the app will receive the github_app_authorization webhook by default. GitHub Apps cannot unsubscribe from this event. Anyone can revoke their authorization of a GitHub App from their GitHub account settings page. Revoking the authorization of a GitHub App does not uninstall the GitHub App. You should program your GitHub App so that when it receives this webhook, it stops calling the API on behalf of the person who revoked the token. If your GitHub App continues to use a revoked access token, it will receive the 401 Bad Credentials error.

User-level permissions

You can add user-level permissions to your GitHub App to access user resources, such as user emails, that are granted by individual users as part of the user authorization flow. User-level permissions differ from repository and organization-level permissions, which are granted at the time of installation on an organization or user account.

You can select user-level permissions from within your GitHub App's settings in the User permissions section of the Permissions & webhooks page. For more information on selecting permissions, see "Editing a GitHub App's permissions."

When a user installs your app on their account, the installation prompt will list the user-level permissions your app is requesting and explain that the app can ask individual users for these permissions.

Because user-level permissions are granted on an individual user basis, you can add them to your existing app without prompting users to upgrade. You will, however, need to send existing users through the user authorization flow to authorize the new permission and get a new user-to-server token for these requests.

User-to-server requests

While most of your API interaction should occur using your server-to-server installation access tokens, certain endpoints allow you to perform actions via the API using a user access token. Your app can make the following requests using GraphQL v4 or REST v3 endpoints.

Supported endpoints

Check Runs

Check Suites

Codes Of Conduct

Deployment Statuses

Deployments

Feeds

Git Blobs

Git Commits

Git Refs

Git Tags

Git Trees

Gitignore Templates

Installations

Issue Assignees

Issue Comments

Issue Events

Issue Timeline

Issues

Labels

Licenses

Markdown

Meta

Milestones

Organization Hooks

Organization Members

Organization Outside Collaborators

Organization Pre Receive Hooks

Organization Team Projects

Organization Team Repositories

Organization Teams

Organizations

Project Collaborators

Projects

Pull Comments

Pull Request Review Events

Pull Request Review Requests

Pull Request Reviews

Pulls

Reactions

Repositories

Repository Activity

Repository Branches

Repository Collaborators

Repository Commit Comments

Repository Commits

Repository Community

Repository Contents

Repository Hooks

Repository Invitations

Repository Keys

Repository Pages

Repository Pre Receive Hooks

Repository Releases

Repository Stats

Root

Search

Statuses

Team Discussions

Topics

User Emails

User Followers

User Gpg Keys

User Public Keys

Users