English
No results found.

Explore by product

Developers
  • Get started
  • Account and profile
  • Authentication
  • Repositories
  • GitHub
  • Enterprise administrators
  • Billing and payments
  • Organizations
  • Code security
  • GitHub Issues
  • GitHub Actions
  • GitHub Codespaces
  • GitHub Packages
  • Search on GitHub
  • Developers
  • REST API
  • GraphQL API
  • GitHub CLI
  • GitHub Discussions
  • GitHub Sponsors
  • Building communities
  • GitHub Pages
  • Education
  • GitHub Desktop
  • Atom
  • Electron
  • CodeQL
  • npm
    • English
  • English
  • 简体中文 (Simplified Chinese)
  • 日本語 (Japanese)
  • Español (Spanish)
  • Português do Brasil (Portuguese)

    • This version of GitHub Enterprise was discontinued on 2021-09-23. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

    Article version

    In this article

    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.

    Note: Expiring user tokens are currently part of the user-to-server token expiration beta and subject to change. To opt-in to the user-to-server token expiration beta feature, see "Activating optional features for apps." For more information, see "Expiring user-to-server access tokens for GitHub Apps."

    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.

    To keep user-to-server access tokens more secure, you can use access tokens that will expire after 8 hours, and a refresh token that can be exchanged for a new access token. For more information, see "Refreshing user-to-server access tokens."

    Identifying users on your site

    To authorize users for standard apps that run in the browser, use the web application flow.

    Web application flow

    Using the web application flow, the process 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

    If you select Request user authorization (OAuth) during installation when creating or modifying your app, step 1 will be completed during app installation. For more information, see "Authorizing users during installation."

    1. Request a user's GitHub identity

    Direct the user to the following URL in their browser:

    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

    NameTypeDescription
    client_idstringRequired. The client ID for your GitHub App. You can find this in your GitHub App settings when you select your app. Note: The app ID and client ID are not the same, and are not interchangeable.
    redirect_uristringThe 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.
    statestringThis should contain a random string to protect against forgery attacks and could contain any other arbitrary data.
    loginstringSuggests a specific account to use for signing in and authorizing the app.
    allow_signupstringWhether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is true. Use false when a policy prohibits signups.

    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.

    Note: If you select Request user authorization (OAuth) during installation when creating or modifying your app, GitHub returns a temporary code that you will need to exchange for an access token. The state parameter is not returned when GitHub initiates the OAuth flow during app installation.

    Exchange this code for an access token. When expiring tokens are enabled, the access token expires in 8 hours and the refresh token expires in 6 months. Every time you refresh the token, you get a new refresh token. For more information, see "Refreshing user-to-server access tokens."

    Expiring user tokens are currently an optional feature and subject to change. To opt-in to the user-to-server token expiration feature, see "Activating optional features for apps."

    Make a request to the following endpoint to receive an access token:

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

    Parameters

    NameTypeDescription
    client_idstringRequired. The client ID for your GitHub App.
    client_secretstringRequired. The client secret for your GitHub App.
    codestringRequired. The code you received as a response to Step 1.
    redirect_uristringThe 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.
    statestringThe unguessable random string you provided in Step 1.

    Response

    By default, the response takes the following form. The response parameters expires_in, refresh_token, and refresh_token_expires_in are only returned when you enable expiring user-to-server access tokens.

    {
  "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
  "expires_in": 28800,
  "refresh_token": "r1.c1b4a2e77838347a7e420ce178f2e7c6912e1692",
  "refresh_token_expires_in": 15811200,
  "scope": "",
  "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 app installations accessible to the user access token and List repositories accessible to the user access token.

    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

    Events

    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 Event Dispatches

    Repository Hooks

    Repository Invitations

    Repository Keys

    Repository Pages

    Repository Pre Receive Hooks

    Repository Releases

    Repository Stats

    Root

    Statuses

    Team Discussions

    Topics

    User Emails

    User Followers

    User Gpg Keys

    User Public Keys

    Users