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

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

Note: GitHub Apps are only compatible with the REST API v3 at this time.

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 https://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.