About authentication options for GitHub Apps

You can authenticate GitHub Apps by either authenticating as an installation or as a GitHub App.

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


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 retrieve high-level management information about your GitHub App and request access tokens for an installation.

To authenticate as a GitHub App, generate a private key. Use this key to sign a JSON Web Token (JWT), and encode using the RS256 algorithm. GitHub checks that the request is authenticated by verifying the token with the integration's stored public key.

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

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

# Private key contents
private_pem = File.read(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: 42 <replace with your id>

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

After creating the JWT, you need to set it in the Header of the request:

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

The example above is using the maximum expiration time of ten 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"

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 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 payload generated above:

curl -i -X POST \
-H "Authorization: Bearer $JWT" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
Status: 201 Created
  "token": "v1.1f699f1069f60xxx",
  "expires_at": "2016-07-11T22:14:10Z"

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

curl -i \
-H "Authorization: token $INSTALLATION_TOKEN" \
-H "Accept: application/vnd.github.machine-man-preview+json" \

HTTP-based Git access by an installation

Installations with permissions on "contents" of a repository, can use their access tokens to authenticate for Git access. The token is used as the HTTP password.

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