Identifying 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.

GitHub App can perform 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 Integration, you must provide a custom media type in the Accept Header for your requests.

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

Identifying users on your site

If your GitHub App specifies a callback_url, you can identify GitHub users when they visit your site using OAuth.

The flow to identify users on your site is:

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

1. Users are redirected to request their GitHub identity

GET http://github.com/login/oauth/authorize

Parameters

Name Type Description
client_id string Required. The client ID you received from GitHub for your GitHub 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.

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 https://github.com/login/oauth/access_token

Parameters

Name Type Description
client_id string Required. The client ID you received from GitHub for your GitHub App.
client_secret string Required. The client secret you received from GitHub 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.

GET https://api.github.com/user?access_token=...

You can pass the token in the query params as shown above, but a cleaner approach is to include it in the Authorization header.

Authorization: token OAUTH-TOKEN

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

curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/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.

GET /user/installations?access_token=...

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

GET /user/installations/:installation_id/repositories?access_token=...

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

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.

Supported Endpoints

  • Get the authenticated user: GET /user
  • Get the authenticated user's Marketplace purchases: GET /user/marketplace_purchases
  • Get stubbed Marketplace purchase data: GET /user/marketplace_purchases/stubbed
  • List installations for user: GET /user/installations
  • List repositories accessible to the user for an installation: GET /user/installations/:installation_id/repositories
  • Create an issue: POST /repos/:owner/:repo/issues
  • List a repository's issue comments: GET /repos/:owner/:repo/issues/comments
  • List a single issue's comments: GET /repos/:owner/:repo/issues/:id/comments
  • Get a single issue comment: GET /repos/:owner/:repo/issues/comments/:id
  • Create an issue comment: POST /repos/:owner/:repo/issues/:number/comments
  • Set the milestone for an issue: PATCH /repos/:owner/:repo/issues/:number
  • Add a label to an issue: POST /repos/:owner/:repo/issues/:number/labels
  • List a repository's pull requests: GET /repos/:owner/:repo/pulls
  • Create a deployment: POST /repos/:owner/:repo/deployments
  • Create a deployment status: POST /repos/:owner/:repo/deployments/:id/statuses