Генерация токена доступа пользователя для приложения GitHub

Сведения о маркерах доступа пользователей

Маркер доступа пользователя — это тип маркера OAuth. В отличие от традиционного маркера OAuth, маркер доступа пользователя не использует области. Вместо этого он использует точные разрешения. Маркер доступа пользователя имеет только разрешения, имеющиеся как у пользователя, так и у приложения. Например, если приложению было предоставлено разрешение на запись содержимого репозитория, но пользователь может только прочитать содержимое, то маркер доступа пользователя может прочитать только содержимое.

Аналогичным образом маркер доступа пользователя может получить доступ только к ресурсам, к которым может обращаться пользователь и приложение. Например, если приложению предоставлен доступ к репозиторию A и пользователь может получить доступ к репозиториюB, а B``Cмаркер доступа пользователя может получить доступ к репозиториюB, но не A к нейC. С помощью REST API можно проверить, какие установки и какие репозитории в установке маркера доступа пользователя могут получить доступ. Дополнительные сведения см GET /user/installations . и GET /user/installations/{installation_id}/repositories в Конечные точки REST API для установки GitHub App.

При выполнении запросов API с маркером доступа пользователей применяются ограничения скорости маркеров доступа пользователей. Дополнительные сведения см. в разделе Ограничения по тарифам для приложений GitHub.

По умолчанию срок действия маркера доступа пользователя истекает через 8 часов. Маркер обновления можно использовать для повторного создания маркера доступа пользователей. Дополнительные сведения см. в разделе Обновление маркеров доступа пользователей.

Пользователи могут отозвать авторизацию GitHub App. Дополнительные сведения см. в разделе Истечение срока действия и отзыв маркера. Если пользователь отменяет авторизацию GitHub App, приложение получит github_app_authorization веб-перехватчик. GitHub Apps не может отменить подписку из этого события. Если приложение получает этот веб-перехватчик, необходимо прекратить вызов API от имени пользователя, который отозвал маркер. Если приложение продолжает использовать отозванный маркер доступа, оно получит ошибку 401 Bad Credentials . Дополнительные сведения об этом веб-перехватчике см. в разделе События и полезные данные веб-перехватчика.

Необходимо обеспечить безопасность маркеров доступа пользователей и маркеров обновления. Дополнительные сведения см. в разделе Лучшие практики создания приложения на GitHub.

Создание маркера доступа пользователей с помощью потока веб-приложения

Если приложение выполняется в браузере, необходимо использовать поток веб-приложения для создания маркера доступа пользователей. Руководство по использованию потока веб-приложения см. в разделе Создание кнопки «Войти с помощью GitHub» с помощью приложения GitHub.

1. Направьте пользователя на этот URL-адрес и добавьте все необходимые параметры запроса из следующего списка параметров: https://github.com/login/oauth/authorize Например, этот URL-адрес указывает client_id и state параметры: https://github.com/login/oauth/authorize?client_id=12345&state=abcdefg

   Параметр запроса	Тип	Обязательное?	Description
   client_id	string	Обязательное поле	Идентификатор клиента для GitHub App. Идентификатор клиента отличается от идентификатора приложения. Идентификатор клиента можно найти на странице параметров приложения. Дополнительные сведения о переходе на страницу параметров для GitHub Appсм. в разделе Изменение регистрации приложения GitHub.
   redirect_uri	string	Настоятельно рекомендуется	URL-адрес в приложении, на который пользователи будут направляться после авторизации. Это должно быть точное соответствие одному из URL-адресов, предоставленных в качестве URL-адреса обратного вызова в параметрах приложения, и не может содержать дополнительные параметры.
   state	string	Настоятельно рекомендуется	При указании значение должно содержать случайную строку для защиты от подделки атак, а также может содержать любые другие произвольные данные.
   code_challenge	string	Настоятельно рекомендуется	Используется для защиты потока проверки подлинности с помощью PKCE (ключ проверки подлинности для Exchange кода). Является обязательным, если указан параметр code_challenge_method. Должен быть 43 символом SHA-256 хэша случайной строки, созданной клиентом. Дополнительные сведения об этом расширении безопасности см. в rfC PKCE.
   code_challenge_method	string	Настоятельно рекомендуется	Используется для защиты потока проверки подлинности с помощью PKCE (ключ проверки подлинности для Exchange кода). Является обязательным, если указан параметр code_challenge. Должно быть S256 : plain метод вызова кода не поддерживается.
   login	string	Необязательно	При указании поток веб-приложения предложит пользователям использовать определенную учетную запись для входа и авторизации приложения.
   allow_signup	boolean	Необязательно	Будут ли пользователи без проверки подлинности предлагать возможность регистрации для GitHub во время потока OAuth. Значение по умолчанию — true. Используйте значение false, когда политика запрещает регистрацию.
   prompt	string	Необязательно	Заставляет средство выбора учетной записи отображаться, если задано select_accountзначение . Средство выбора учетных записей также появится, если у приложения есть URI перенаправления, отличный от HTTP, или если у пользователя есть несколько учетных записей, вошедшего в систему.

2. Если пользователь принимает запрос авторизации, GitHub перенаправит пользователя на один из URL-адресов обратного вызова в параметрах приложения и укажите code параметр запроса, который можно использовать на следующем шаге для создания маркера доступа пользователя. Если вы указали redirect_uri на предыдущем шаге, будет использоваться URL-адрес обратного вызова. В противном случае будет использоваться первый URL-адрес обратного вызова на странице параметров приложения.

   Если вы указали state параметр на предыдущем шаге, GitHub также будет включать state параметр. state Если параметр не соответствует параметруstate, отправленного на предыдущем шаге, запрос не может быть доверенным, а поток веб-приложения должен быть прерван.

3. Обмен данными code из предыдущего шага для маркера доступа пользователя путем отправки POST запроса на этот URL-адрес вместе со следующими параметрами запроса: https://github.com/login/oauth/access_token

   Параметр запроса	Тип	Описание
   client_id	string	Необходимые. Идентификатор клиента для GitHub App. Идентификатор клиента отличается от идентификатора приложения. Идентификатор клиента можно найти на странице параметров приложения. Дополнительные сведения о переходе на страницу параметров для GitHub Appсм. в разделе Изменение регистрации приложения GitHub.
   client_secret	string	Необходимые. Секрет клиента для GitHub App. Вы можете создать секрет клиента на странице параметров приложения.
   code	string	Необходимые. Полученный код на предыдущем шаге.
   redirect_uri	string	URL-адрес в приложении, на который пользователи будут направляться после авторизации. Это должно быть точное соответствие одному из URL-адресов, предоставленных в качестве URL-адреса обратного вызова при настройке GitHub App и не может содержать дополнительные параметры.
   code_verifier	string	Настоятельно рекомендуется. Используется для защиты потока проверки подлинности с помощью PKCE (ключ проверки подлинности для Exchange кода). Требуется, если code_challenge он был отправлен во время авторизации пользователя. Должно быть исходное значение, используемое для создания code_challenge в запросе авторизации. Это может храниться в файле cookie вместе с state параметром или в переменной сеанса во время проверки подлинности в зависимости от архитектуры приложения.
   repository_id	string	Идентификатор одного репозитория, к которому может получить доступ маркер доступа пользователя. Если GitHub App или пользователь не может получить доступ к репозиторию, это будет игнорироваться. Используйте этот параметр, чтобы дополнительно ограничить доступ маркера доступа пользователя.

4. GitHub даст ответ, содержащий следующие параметры:

   Параметр ответа	Тип	Описание
   access_token	string	Маркер доступа пользователя. Маркер начинается с ghu_.
   expires_in	integer	Количество секунд до истечения access_token срока действия. Если вы отключили срок действия маркеров доступа пользователей, этот параметр будет опущен. Значение всегда будет ( 28800 8 часов).
   refresh_token	string	Маркер обновления. Если вы отключили срок действия маркеров доступа пользователей, этот параметр будет опущен. Маркер начинается с ghr_.
   refresh_token_expires_in	integer	Количество секунд до истечения refresh_token срока действия. Если вы отключили срок действия маркеров доступа пользователей, этот параметр будет опущен. Значение всегда будет ( 15897600 6 месяцев).
   scope	string	Области, имеющиеся у маркера. Это значение всегда будет пустой строкой. В отличие от традиционного маркера OAuth, маркер доступа пользователя ограничен разрешениями, которые имеют ваше приложение и пользователь.
   token_type	string	Тип токена. Значение всегда будет.bearer

5. Используйте маркер доступа пользователя на предыдущем шаге, чтобы запросить API от имени пользователя. Включите маркер доступа пользователя в Authorization заголовок запроса API. Например:

   curl --request GET \
   --url "https://api.github.com/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN" \
   --header "X-GitHub-Api-Version: 2026-03-10"
   

Создание маркера доступа пользователей с помощью потока устройства

Если ваше приложение находится без головы или не имеет доступа к браузеру, следует использовать поток устройства для создания маркера доступа пользователей. Например, средства CLI, простые Raspberry Pis и классические приложения должны использовать поток устройств. Руководство по использованию потока устройств см. в разделе Создание CLI с помощью приложения GitHub.

Прежде чем использовать поток устройства, необходимо сначала включить его в параметрах приложения. Дополнительные сведения о включении потока устройств см. в разделе Изменение регистрации приложения GitHub.

Поток устройства использует разрешение на авторизацию устройства OAuth 2.0.

1.        `POST` Отправьте запрос `https://github.com/login/device/code` вместе с параметром `client_id` запроса. Идентификатор клиента отличается от идентификатора приложения. Идентификатор клиента можно найти на странице параметров приложения. Дополнительные сведения о переходе на страницу параметров для GitHub Appсм. в разделе [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings).
   

2. GitHub даст ответ, содержащий следующие параметры запроса:

   Параметр ответа	Тип	Description
   device_code	string	Код проверки, используемый для проверки устройства. Этот код составляет 40 символов.
   user_code	string	Код проверки, отображаемый приложением, чтобы пользователь смог ввести код в браузере. Он состоит из восьми символов с дефисом в середине. Например: WDJB-MJHT.
   verification_uri	string	URL-адрес, в котором пользователям нужно ввести их user_code. URL-адрес: https://github.com/login/device.
   expires_in	integer	Количество секунд до окончания срока действия device_code и user_code. Значение по умолчанию — 900 секунд (15 минут).
   interval	integer	Минимальное количество секунд, которое должно пройти, прежде чем можно будет выполнить новый запрос маркера доступа (POST https://github.com/login/oauth/access_token) для завершения авторизации устройства. Если вы выполняете запрос до прохождения этого интервала, то вы получите ошибку slow_down . Значение по умолчанию — 5 секунд.

3. Предложите пользователю ввести user_code предыдущий шаг на https://github.com/login/device.

   Если пользователь не вводит код до expires_in истечения времени, код будет недопустимым. В этом случае необходимо перезапустить поток устройства.

4. Опрос POST https://github.com/login/oauth/access_token вместе с client_id``device_codeпараметрами запроса и параметрами запроса (описанными ниже) до истечения срока действия кодов устройств и grant_type пользователей или пользователь успешно авторизовал приложение, введя егоuser_code.

   Параметр запроса	Тип	Description
   client_id	string

          **Обязательно**. Идентификатор клиента для GitHub App.
   

   device_code | string | Обязательно. Код проверки устройства, полученный на предыдущем шаге. grant_type | string | Обязательно. Тип предоставления разрешения должен быть urn:ietf:params:oauth:grant-type:device_code. repository_id | string | Идентификатор одного репозитория, к которому может получить доступ маркер доступа пользователя. Если GitHub App или пользователь не может получить доступ к репозиторию, это будет игнорироваться. Используйте этот параметр, чтобы дополнительно ограничить доступ маркера доступа пользователя.

   Не опрашивайте эту конечную точку с более высокой частотой, чем частота, указанная intervalна . Если вы сделаете это, вы получите ошибку slow_down . Ответ об ошибке slow_down добавляет пять секунд к последнему интервалу interval.

   Пока пользователь не введет код, GitHub будет отвечать с состоянием 200 и параметром error запроса ответа.

   Имя ошибки	Description
   authorization_pending	Эта ошибка возникает, если запрос авторизации ожидает завершения и пользователь еще не ввел код проверки пользователя. Ожидается, что приложение будет держать опрос на POST https://github.com/login/oauth/access_token частоте не быстрее, чем частота, указанная в параметре interval.
   slow_down	При получении ошибки slow_down к минимальному интервалу времени interval между запросами POST https://github.com/login/oauth/access_token добавляются пять дополнительных секунд. Например, если начальный интервал требует не менее 5 секунд между запросами и ответом slow_down на ошибку, необходимо ждать не менее 10 секунд, прежде чем выполнять новый запрос на маркер. В ответе с ошибкой указывается новый интервал interval, который необходимо выждать.
   expired_token	Если истек срок действия кода устройства, возникнет ошибка token_expired. Необходимо запросить новый код устройства.
   unsupported_grant_type	Тип предоставления разрешения должен быть urn:ietf:params:oauth:grant-type:device_code и включен в качестве входного параметра при запросе маркера OAuth POST https://github.com/login/oauth/access_token.
   incorrect_client_credentials	Для процесса для устройства необходимо передать идентификатор клиента приложения, который можно найти на странице параметров приложения. Идентификатор клиента отличается от идентификатора приложения и секрета клиента.
   incorrect_device_code	Предоставленный device_code параметр недопустим.
   access_denied	Когда пользователь нажимает кнопку "Отменить" во время процесса авторизации, вы получите access_denied ошибку, и пользователь снова не сможет использовать код проверки.
   device_flow_disabled	Процесс для устройства не включен в параметрах приложения. Дополнительные сведения о включении потока устройств см. в разделе Изменение регистрации приложения GitHub.

5. После ввода user_codeпользователя GitHub даст ответ, содержащий следующие параметры запроса:

   Параметр ответа	Тип	Описание
   access_token	string	Маркер доступа пользователя. Маркер начинается с ghu_.
   expires_in	integer	Количество секунд до истечения access_token срока действия. Если вы отключили срок действия маркеров доступа пользователей, этот параметр будет опущен. Значение всегда будет ( 28800 8 часов).
   refresh_token	string	Маркер обновления. Если вы отключили срок действия маркеров доступа пользователей, этот параметр будет опущен. Маркер начинается с ghr_.
   refresh_token_expires_in	integer	Количество секунд до истечения refresh_token срока действия. Если вы отключили срок действия маркеров доступа пользователей, этот параметр будет опущен. Значение всегда будет ( 15897600 6 месяцев).
   scope	string	Области, имеющиеся у маркера. Это значение всегда будет пустой строкой. В отличие от традиционного маркера OAuth, маркер доступа пользователя ограничен разрешениями, которые имеют ваше приложение и пользователь.
   token_type	string	Тип токена. Значение всегда будет.bearer

6. Используйте маркер доступа пользователя на предыдущем шаге, чтобы запросить API от имени пользователя. Включите маркер доступа пользователя в Authorization заголовок запроса API. Например:

   curl --request GET \
   --url "https://api.github.com/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN" \
   --header "X-GitHub-Api-Version: 2026-03-10"
   

Создание маркера доступа пользователя при установке приложения

При выборе запроса авторизации пользователя (OAuth) во время установки в параметрах приложения GitHub начнет поток веб-приложения сразу после установки приложения.

Маркер доступа пользователя можно создать с помощью этого метода независимо от того, установлено ли приложение в учетной записи пользователя или учетной записи организации. Однако если приложение было установлено в учетной записи организации, необходимо использовать поток веб-приложения или поток устройств для создания маркера доступа для других пользователей в организации.

1. Когда пользователь устанавливает приложение, GitHub перенаправит пользователя https://github.com/login/oauth/authorize?client_id=CLIENT_IDв , где CLIENT_ID находится идентификатор клиента вашего приложения.

2. Если пользователь принимает запрос авторизации, GitHub перенаправит пользователя на первый URL-адрес обратного вызова в параметрах приложения и укажите code параметр запроса.

   Если вы хотите управлять используемым URL-адресом обратного вызова, не выбирайте запрос авторизации пользователя (OAuth) во время установки. Вместо этого направляйте пользователей через полный поток веб-приложения и укажите redirect_uri параметр.

3. Обмен данными code из предыдущего шага для маркера доступа пользователя путем отправки POST запроса на этот URL-адрес вместе со следующими параметрами запроса: https://github.com/login/oauth/access_token

   Параметр запроса	Тип	Описание
   client_id	string	Необходимые. Идентификатор клиента для GitHub App. Идентификатор клиента отличается от идентификатора приложения. Идентификатор клиента можно найти на странице параметров приложения. Дополнительные сведения о переходе на страницу параметров для GitHub Appсм. в разделе Изменение регистрации приложения GitHub.
   client_secret	string	Необходимые. Секрет клиента для GitHub App. Вы можете создать секрет клиента на странице параметров приложения.
   code	string	Необходимые. Полученный код на предыдущем шаге.
   redirect_uri	string	URL-адрес в приложении, на который пользователи будут направляться после авторизации. Это должно быть точное соответствие одному из URL-адресов, предоставленных в качестве URL-адреса обратного вызова при настройке GitHub App и не может содержать дополнительные параметры.
   code_verifier	string	Настоятельно рекомендуется. Используется для защиты потока проверки подлинности с помощью PKCE (ключ проверки подлинности для Exchange кода). Требуется, если code_challenge он был отправлен во время авторизации пользователя. Должно быть исходное значение, используемое для создания code_challenge в запросе авторизации. Это может храниться в файле cookie вместе с state параметром или в переменной сеанса во время проверки подлинности в зависимости от архитектуры приложения.
   repository_id	string	Идентификатор одного репозитория, к которому может получить доступ маркер доступа пользователя. Если GitHub App или пользователь не может получить доступ к репозиторию, это будет игнорироваться. Используйте этот параметр, чтобы дополнительно ограничить доступ маркера доступа пользователя.

4. GitHub даст ответ, содержащий следующие параметры:

   Параметр ответа	Тип	Описание
   access_token	string	Маркер доступа пользователя. Маркер начинается с ghu_.
   expires_in	integer	Количество секунд до истечения access_token срока действия. Если вы отключили срок действия маркеров доступа пользователей, этот параметр будет опущен. Значение всегда будет ( 28800 8 часов).
   refresh_token	string	Маркер обновления. Если вы отключили срок действия маркеров доступа пользователей, этот параметр будет опущен. Маркер начинается с ghr_.
   refresh_token_expires_in	integer	Количество секунд до истечения refresh_token срока действия. Если вы отключили срок действия маркеров доступа пользователей, этот параметр будет опущен. Значение всегда будет ( 15897600 6 месяцев).
   scope	string	Области, имеющиеся у маркера. Это значение всегда будет пустой строкой. В отличие от традиционного маркера OAuth, маркер доступа пользователя ограничен разрешениями, которые имеют ваше приложение и пользователь.
   token_type	string	Тип токена. Значение всегда будет.bearer

5. Используйте маркер доступа пользователя на предыдущем шаге, чтобы запросить API от имени пользователя. Включите маркер доступа пользователя в Authorization заголовок запроса API. Например:

   curl --request GET \
   --url "https://api.github.com/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN" \
   --header "X-GitHub-Api-Version: 2026-03-10"
   

Использование маркера обновления для создания маркера доступа пользователей

По умолчанию срок действия маркеров доступа пользователей истекает через 8 часов. Если вы получаете маркер доступа пользователя с истечением срока действия, вы также получите маркер обновления. Срок действия маркера обновления истекает через 6 месяцев. Этот маркер обновления можно использовать для повторного создания маркера доступа пользователей. Дополнительные сведения см. в разделе Обновление маркеров доступа пользователей.

GitHub настоятельно рекомендует использовать маркеры доступа пользователей, срок действия которого истекает. Если вы ранее отказались от использования маркеров доступа пользователей, которые истекают, но хотите повторно включить эту функцию, см . раздел AUTOTITLE.

Устранение неполадок

В следующих разделах описаны некоторые ошибки, которые могут возникнуть при создании маркера доступа пользователя.

Неверные учетные данные клиента

          `client_id` Если указано неправильное или `client_secret` указанное значение, появится сообщение об ошибке`incorrect_client_credentials`.

Чтобы устранить эту ошибку, обязательно используйте правильные учетные данные для ваших GitHub App. Идентификатор клиента и секрет клиента можно найти на странице параметров для GitHub App. Дополнительные сведения о переходе на страницу параметров GitHub App см. в разделе Изменение регистрации приложения GitHub.

Несоответствие URI перенаправления

Если указать redirect_uri , что не соответствует одному из URL-адресов обратного вызова в регистрации GitHub App, появится сообщение об ошибке redirect_uri_mismatch .

Чтобы устранить эту ошибку, укажите redirect_uri один из URL-адресов обратного вызова для регистрации GitHub App или опустите этот параметр по умолчанию для первого URL-адреса обратного вызова, указанного в регистрации GitHub App . Дополнительные сведения см. в разделе Сведения о URL-адресе обратного вызова авторизации пользователя.

Неверный код проверки

Если вы используете поток устройства и указанный код проверки (device_code) неверный, истек или не соответствует значению, полученному из первоначального запроса https://github.com/login/device/code, вы получите ошибку bad_verification_code .

Чтобы устранить эту ошибку, необходимо снова запустить поток устройства, чтобы получить новый код. Дополнительные сведения см. в разделе "Использование потока устройства" для создания маркера доступа пользователей.

Недопустимый маркер обновления

Если указанный маркер обновления недопустим или истек, появится сообщение об ошибке bad_refresh_token .

Чтобы устранить эту ошибку, необходимо перезапустить поток веб-приложения или поток устройства, чтобы получить новый маркер доступа пользователя и маркер обновления. Маркер обновления будет получен только в том случае, если ваш GitHub App отказался от истечения срока действия маркеров доступа пользователей. Дополнительные сведения см. в разделе Обновление маркеров доступа пользователей.

Неподдерживаемый тип предоставления

При запросе маркера доступа пользователя через поток grant_type устройства параметр должен быть urn:ietf:params:oauth:grant-type:device_code. При обновлении маркера доступа пользователя с помощью маркера grant_type обновления параметр должен быть refresh_token. Если вы не используете правильный тип предоставления, вы получите сообщение об ошибке unsupported_grant_type .

Неверифицированное сообщение электронной почты пользователя

Если пользователь, для которого вы пытаетесь создать маркер доступа пользователя, не проверил свои основной адрес электронной почты с помощью GitHub, появится сообщение об ошибкеunverified_user_email.

Чтобы устранить эту ошибку, предложите пользователю проверить основной адрес электронной почты в учетной записи GitHub . Дополнительные сведения см. в разделе Подтверждение адреса электронной почты.