jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-23 11:54:18 -05:00
Code Issues Projects Releases Wiki Activity
Files
840fb65b2ac5e26919a7b792df9c88879809edab
docs/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md
Sarah Edwards 5259006251 Identifying and authorizing users (#35154) 
Co-authored-by: Jess Hosman <1183847+jhosman@users.noreply.github.com>
Co-authored-by: Niky <20468684+nikymorg@users.noreply.github.com>
2023-03-08 23:12:24 +00:00

52 KiB
Raw Blame History

title, intro, versions, topics, shortTitle
title intro versions topics shortTitle
Generating a user access token for a GitHub App You can generate a user access token for your {% data variables.product.prodname_github_app %} in order to attribute app activity to a user.
fpt ghes ghae ghec
* * * *
GitHub Apps
Generate a user access token

About user access tokens

{% data reusables.pre-release-program.expiring-user-access-tokens %}

A user access token is a type of OAuth token. Unlike a traditional OAuth token, the user access token does not use scopes. Instead, it uses fine-grained permissions. A user access token only has permissions that both the user and the app have. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents.

Similarly, a user access token can only access resources that both the user and app can access. For example, if an app is granted access to repository A and B, and the user can access repository B and C, the user access token can access repository B but not A or C. You can use the REST API to check which installations and which repositories within an installation a user access token can access. For more information, see GET /user/installations and GET /user/installations/{installation_id}/repositories in "AUTOTITLE."

When you make API requests with a user access token, the rate limits for user access tokens apply. For more information, see "AUTOTITLE."

By default, the user access token expires after 8 hours. You can use a refresh token to regenerate a user access token. For more information, see "AUTOTITLE."

Users can revoke their authorization of a {% data variables.product.prodname_github_app %}. For more information, see "AUTOTITLE." If a user revokes their authorization of a {% data variables.product.prodname_github_app %}, the app will receive the github_app_authorization webhook. {% data variables.product.prodname_github_apps %} cannot unsubscribe from this event. If your app receives this webhook, you should stop calling the API on behalf of the user who revoked the token. If your app continues to use a revoked access token, it will receive the 401 Bad Credentials error. For more information about this webhook, see "AUTOTITLE"

Using the web application flow to generate a user access token

If your app runs in the browser, you should use the web application flow to generate a user access token.

  1. Direct the user to this URL, and add any necessary query parameters from the following list of parameters: {% data variables.product.oauth_host_code %}/login/oauth/authorize. For example, this URL specifies the client_id and state parameters: {% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=12345&state=abcdefg.

    Query parameter Type Description
    client_id string Required. The client ID for your {% data variables.product.prodname_github_app %}. The client ID is different from the app ID. You can find the client ID on the settings page for your app.

    For user-owned apps, the settings page is https://github.com/settings/apps/APP-SLUG.

    For organization-owned apps, the settings page is https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.

    Replace APP-SLUG with the sluggified name of your app and ORGANIZATION with the sluggified name of your organization. For example, https://github.com/organizations/octo-org/settings/apps/octo-app.
    redirect_uri string The URL in your application where users will be sent after authorization. This must be an exact match to one of the URLs you provided as a "Callback URL" in your app's settings and can't contain any additional parameters.
    state string When specified, the value should contain a random string to protect against forgery attacks, and it can also contain any other arbitrary data.
    login string When specified, the web application flow will prompt users with a specific account they can use for signing in and authorizing your app.
    allow_signup boolean Whether unauthenticated users will be offered an option to sign up for {% data variables.product.prodname_dotcom %} during the OAuth flow. The default is true. Use false when a policy prohibits signups.

  2. If the user accepts your authorization request, {% data variables.product.company_short %} will redirect the user to one of the callback URLs in your app settings, and provide a code query parameter you can use in the next step to create a user access token. If you specified redirect_uri in the previous step, that callback URL will be used. Otherwise, the first callback URL on your app's settings page will be used.

    If you specified the state parameter in the previous step, {% data variables.product.company_short %} will also include a state parameter. If the state parameter does not match the state parameter that you sent in the previous step, the request cannot be trusted, and the web application flow should be aborted.

{% data reusables.apps.web-app-flow-exchange-code %}

{% data reusables.apps.web-app-flow-token-response %}

{% data reusables.apps.user-access-token-example-request %}

Using the device flow to generate a user access token

{% note %}

Note: The device flow is in public beta and subject to change.

{% endnote %}

If your app is headless or does not have access to a browser, you should use the device flow to generate a user access token. For example, CLI tools or Git credential mangers should use the device flow.

{% ifversion device-flow-is-opt-in %}Before you can use the device flow to identify and authorize users, you must first enable it in your app's settings. For more information on enabling device flow, see "AUTOTITLE." {% endif %}

The device flow uses the OAuth 2.0 Device Authorization Grant.

  1. Send a POST request to {% data variables.product.oauth_host_code %}/login/device/code along with a client_id query parameter. The client ID is different from the app ID. You can find the client ID on the settings page for your app.

    • For user-owned apps, the settings page is https://github.com/settings/apps/APP-SLUG.
    • For organization-owned apps, the settings page is https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.

    Replace APP-SLUG with the sluggified name of your app and ORGANIZATION with the sluggified name of your organization. For example, https://github.com/organizations/octo-org/settings/apps/octo-app.

  2. {% data variables.product.company_short %} will respond with a response that includes the following parameters:

    Response parameter Type Description
    device_code string A verification code that is used to verify the device. This code is 40 characters long.
    user_code string A verification code that your application should display so that the user can enter the code in a browser. This code is 8 characters with a hyphen in the middle. For example, WDJB-MJHT.
    verification_uri string The URL where users need to enter their user_code. The URL is: {% data variables.product.device_authorization_url %}.
    expires_in integer The number of seconds before the device_code and user_code expire. The default is 900 seconds (15 minutes).
    interval integer The minimum number of seconds that must pass before you can make a new access token request (POST {% data variables.product.oauth_host_code %}/login/oauth/access_token) to complete the device authorization. If you make a request before this interval passes, then you will hit the rate limit and receive a slow_down error. The default is 5 seconds.

  3. Prompt the user to enter the user_code from the previous step at {% data variables.product.device_authorization_url %}.

    If the user does not enter the code before the expires_in time passes, the code will be invalid. In this case, you should restart the device flow.

  4. Poll POST {% data variables.product.oauth_host_code %}/login/oauth/access_token along with the client_id, device_code, and grant_type query parameters (described below) until the device and user codes expire or the user has successfully authorized the app by entering the user_code.

    Query parameter Type Description
    client_id string Required. The client ID for your {% data variables.product.prodname_github_app %}.
    device_code string Required. The device verification code you received in the previous step.
    grant_type string Required. The grant type must be urn:ietf:params:oauth:grant-type:device_code.

    Do not poll this endpoint at a higher frequency than the frequency indicated by interval. If you do, you will hit the rate limit and receive a slow_down error. The slow_down error response adds 5 seconds to the last interval.

  5. Once the user has entered the user_code, {% data variables.product.company_short %} will respond with a response body that includes the following parameters:

    {% data reusables.apps.user-access-token-response-parameters %}

{% data reusables.apps.user-access-token-example-request %}

Error codes for the device flow

Error code Description
authorization_pending This error occurs when the authorization request is pending and the user hasn't entered the user code yet. The app is expected to keep polling the POST {% data variables.product.oauth_host_code %}/login/oauth/access_token at a frequency no faster than the frequency specified by interval.
slow_down When you receive the slow_down error, 5 extra seconds are added to the minimum interval or timeframe required between your requests using POST {% data variables.product.oauth_host_code %}/login/oauth/access_token. For example, if the starting interval required at least 5 seconds between requests and you get a slow_down error response, you must now wait a minimum of 10 seconds before making a new request for a token. The error response includes the new interval that you must use.
expired_token If the device code expired, then you will see the token_expired error. You must make a new request for a device code.
unsupported_grant_type The grant type must be urn:ietf:params:oauth:grant-type:device_code and included as an input parameter when you poll the OAuth token request POST {% data variables.product.oauth_host_code %}/login/oauth/access_token.
incorrect_client_credentials For the device flow, you must pass your app's client ID, which you can find on your app settings page. The client ID is different from the app ID and client secret.
incorrect_device_code The device_code provided is not valid.
access_denied When a user clicks cancel during the authorization process, you'll receive an access_denied error, and the user won't be able to use the verification code again.{% ifversion device-flow-is-opt-in %}
device_flow_disabled Device flow has not been enabled in the app's settings. For more information on enabling device flow, see "AUTOTITLE."{% endif %}

Generating a user access token when a user installs your app

If you select Request user authorization (OAuth) during installation in your app settings, {% data variables.product.company_short %} will start the web application flow immediately after a user installs your app.

You can generate a user access token with this method regardless of whether the app is installed on a user account or an organization account. However, if the app was installed on an organization account, you will need to use the web application flow or device flow to generate a user access token for other users in the organization.

  1. When a user installs your app, {% data variables.product.company_short %} will redirect the user to {% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=CLIENT_ID, where CLIENT_ID is the client ID of your app.

  2. If the user accepts your authorization request, {% data variables.product.company_short %} will redirect the user to the first callback URL in your app settings, and provide a code query parameter.

    If you want to control which callback URL is used, do not select Request user authorization (OAuth) during installation. Instead, direct users through the full web application flow and specify the redirect_uri parameter.

{% data reusables.apps.web-app-flow-exchange-code %}

{% data reusables.apps.web-app-flow-token-response %}

{% data reusables.apps.user-access-token-example-request %}

Using a refresh token to generate a user access token

By default, user access tokens expires after 8 hours. If you receive a user access token with an expiration, you will also receive a refresh token. The refresh token expire after 6 months. You can use this refresh token to regenerate a user access token. For more information, see "AUTOTITLE."

{% data variables.product.company_short %} strongly encourages you to use user access tokens that expire. If you previously opted out of using user access tokens that expire but want to reenable this feature, see "AUTOTITLE".

Supported endpoints for user access tokens

{% ifversion fpt or ghec %}

Actions Runners

Actions Secrets

{% ifversion fpt or ghec %}

Artifacts

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

{% ifversion fpt or ghec %}

Interaction Limits

Issue Assignees

Issue Comments

Issue Events

Issue Timeline

Issues

{% ifversion fpt or ghec %}

Jobs

Labels

Licenses

Markdown

Meta

Milestones

Organization Hooks

{% ifversion fpt or ghec %}

Organization Invitations

Organization Members

Organization Outside Collaborators

{% ifversion ghes %}

Organization Pre Receive Hooks

Organization Team Projects

Organization Team Repositories

{% ifversion fpt or ghec %}

Organization Team Sync

Organization Teams

Organizations

{% ifversion fpt or ghec %}

Organizations Credential Authorizations

{% ifversion fpt or ghec %}

Organizations Scim

{% ifversion fpt or ghec %}

Source Imports

Project Collaborators

Projects

Pull Comments

Pull Request Review Events

Pull Request Review Requests

Pull Request Reviews

Pulls

Reactions

Repositories

Repository Activity

{% ifversion fpt or ghec %}

Repository Automated Security Fixes

Repository Branches

Repository Collaborators

Repository Commit Comments

Repository Commits

Repository Community

Repository Contents

Repository Event Dispatches

Repository Hooks

Repository Invitations

Repository Keys

Repository Pages

{% ifversion ghes %}

Repository Pre Receive Hooks

Repository Releases

Repository Stats

{% ifversion fpt or ghec %}

Repository Vulnerability Alerts

Root

Search

Statuses

Team Discussions

Topics

{% ifversion fpt or ghec %}

Traffic

{% ifversion fpt or ghec %}

User Blocking

{% ifversion fpt or ghes or ghec %}

User Emails

{% ifversion fpt or ghec %}

User Followers

User Gpg Keys

User Public Keys

Users

{% ifversion fpt or ghec %}

Workflow Runs

{% ifversion fpt or ghec %}

Workflows

Reference in New Issue View Git Blame Copy Permalink