Authentication options for GitHub Apps

You can authenticate as a GitHub App or as an installation.

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.

Authenticating as a GitHub App

Authenticating as a GitHub App lets you do a couple of things:

  • You can retrieve high-level management information about your GitHub App.
  • You can request access tokens for an installation of the app.

To authenticate as a GitHub App, generate a private key in PEM format and download it to your local machine. You'll use this key to sign a JSON Web Token (JWT) and encode it using the RS256 algorithm. GitHub checks that the request is authenticated by verifying the token with the app's stored public key.

Here's a quick Ruby script you can use to generate a JWT. Note you'll have to run gem install jwt before using it.

require 'openssl'
require 'jwt'  # https://rubygems.org/gems/jwt

# Private key contents
private_pem = File.read(YOUR_PATH_TO_PEM)
private_key = OpenSSL::PKey::RSA.new(private_pem)

# Generate the JWT
payload = {
  # issued at time
  iat: Time.now.to_i,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
  # GitHub App's identifier
  iss: YOUR_ISSUE_NUMBER
}

jwt = JWT.encode(payload, private_key, "RS256")
puts jwt

YOUR_PATH_TO_PEM and YOUR_ISSUE_NUMBER are the values you must replace.

For the iss issuer claim (YOUR_ISSUE_NUMBER), you can obtain the GitHub App identifier via the initial webhook ping after creating the app, or at any time from the app settings page in the web UI.

After creating the JWT, set it in the Header of the API request:

curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github.machine-man-preview+json" https://api.github.com/app

YOUR_JWT is the value you must replace.

The example above uses the maximum expiration time of 10 minutes, after which the API will start returning a 401 error:

{
  "message": "'Expiration' claim ('exp') must be a numeric value representing the future time at which the assertion expires.",
  "documentation_url": "https://developer.github.com/v3"
}

You'll need to create a new JWT after the time expires.

Accessing API endpoints as a GitHub App

For a list of REST API v3 endpoints you can use to get high-level information about a GitHub App, see "GitHub Apps."

For a list of REST API v3 endpoints that are available for use by GitHub Apps, see "Available Endpoints."

Authenticating as an installation

Authenticating as an installation lets you perform actions in the API for that installation. Before authenticating as an installation, you must create an installation access token. These installation access tokens are used by GitHub Apps to authenticate.

Installation access tokens are scoped to the repositories an installation can access, have defined permissions set by the GitHub App, and expire after one hour.

To create an installation access token, include the JWT generated above in the Authorization header in the API request:

curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
https://api.github.com/installations/:installation_id/access_tokens

The response will include your installation access token:

Status: 201 Created
{
  "token": "v1.1f699f1069f60xxx",
  "expires_at": "2016-07-11T22:14:10Z"
}

To authenticate with an installation access token, include it in the Authorization header in the API request:

curl -i \
-H "Authorization: token YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
https://api.github.com/installation/repositories

YOUR_INSTALLATION_ACCESS_TOKEN is the value you must replace.

Accessing API endpoints as an installation

For a list of REST API v3 endpoints that are available while authenticated as an installation, see "Available Endpoints."

HTTP-based Git access by an installation

Installations with permissions on contents of a repository, can use their installation access tokens to authenticate for Git access. Use the installation access token as the HTTP password:

git clone https://x-access-token:<token>@github.com/owner/repo.git