Skip to content

Commit

Permalink
Merge branch 'main' into patch-1
Browse files Browse the repository at this point in the history
  • Loading branch information
@cmwilson21
cmwilson21 authored Mar 31, 2023
2 parents 5ac2144 + b57421f commit 5a6c22b
Show file tree
Hide file tree
Showing 6 changed files with 785 additions and 28 deletions.
32 changes: 16 additions & 16 deletions ...enticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ If your app runs in the browser, you should use the web application flow to gene

{% 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.
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, simple Raspberry Pis, and desktop applications should use the device flow.

{% ifversion device-flow-is-opt-in %}Before you can use the device flow, you must first enable it in your app's settings. For more information on enabling device flow, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)." {% endif %}

Expand All @@ -69,7 +69,7 @@ The device flow uses the OAuth 2.0 Device Authorization Grant.

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

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

Response parameter | Type | Description
--- | --- | ---
Expand All @@ -91,25 +91,25 @@ The device flow uses the OAuth 2.0 Device Authorization Grant.

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`.

1. Once the user has entered the `user_code`, {% data variables.product.company_short %} will respond with a response body that includes the following parameters:
Until the user enters the code, {% data variables.product.company_short %} will respond with a 200 status and an `error` response query parameter.

| Error name | 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](/apps/maintaining-github-apps/modifying-a-github-app)."{% endif %}

1. Once the user has entered the `user_code`, {% data variables.product.company_short %} will give a response that includes the following query 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](/apps/maintaining-github-apps/modifying-a-github-app)."{% 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.
Expand Down
2 changes: 1 addition & 1 deletion ...g-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,6 @@ If you opt into user access tokens that expire after you have already generated
`grant_type` | `string` | **Required.** The value must be "refresh_token".
`refresh_token` | `string` | **Required.** The refresh token that you received when you generated a user access token.

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

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

0 comments on commit 5a6c22b

Please sign in to comment.