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

About 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 "GitHub App installations."

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

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 "Refreshing user access tokens."

Users can revoke their authorization of a GitHub App. For more information, see "Token expiration and revocation." If a user revokes their authorization of a GitHub App, the app will receive the github_app_authorization webhook. 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 "Webhook events and payloads."

You should keep user access tokens and refresh tokens secure. For more information, see "Best practices for creating a GitHub App."

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. For a tutorial about using the web application flow, see "Building a "Login with GitHub" button with a GitHub App."

1. Direct the user to this URL, and add any necessary query parameters from the following list of parameters: http(s)://HOSTNAME/login/oauth/authorize. For example, this URL specifies the client_id and state parameters: http(s)://HOSTNAME/login/oauth/authorize?client_id=12345&state=abcdefg.

   Query parameter	Type	Description
   client_id	string	Required. The client ID for your 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 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.
   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 GitHub during the OAuth flow. The default is true. Use false when a policy prohibits signups.

2. If the user accepts your authorization request, GitHub 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, GitHub 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.

3. Exchange the code from the previous step for a user access token by making a POST request to this URL, along with the following query parameters: http(s)://HOSTNAME/login/oauth/access_token

   Query parameter	Type	Description
   client_id	string	Required. The client ID for your 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 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.
   client_secret	string	Required. The client secret for your GitHub App. You can generate a client secret on the settings page for your app.
   code	string	Required. The code you received in the previous step.
   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" when setting up your GitHub App and can't contain any additional parameters.
   repository_id	string	The ID of a single repository that the user access token can access. If the GitHub App or user cannot access the repository, this will be ignored. Use this parameter to restrict the access of the user access token further.

4. GitHub will give a response that includes the following parameters:

   Response parameter	Type	Description
   access_token	string	The user access token. The token starts with ghu_.
   expires_in	integer	The number of seconds until access_token expires. If you disabled expiration of user access tokens, this parameter will be omitted. The value will always be 28800 (8 hours).
   refresh_token	string	The refresh token. If you disabled expiration of user access tokens, this parameter will be omitted. The token starts with ghr_.
   refresh_token_expires_in	integer	The number of seconds until refresh_token expires. If you disabled expiration of user access tokens, this parameter will be omitted. The value will always be 15811200 (6 months).
   scope	string	The scopes that the token has. This value will always be an empty string. Unlike a traditional OAuth token, the user access token is limited to the permissions that both your app and the user have.
   token_type	string	The type of token. The value will always be bearer.

5. Use the user access token from the previous step to make API requests on behalf of the user. Include the user access token in the Authorization header of an API request. For example:

   curl --request GET \
   --url "http(s)://HOSTNAME/api/v3/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN"

Using the device flow to generate a user access token

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. For a tutorial that uses device flow, see "Building a CLI with a GitHub App."

The device flow uses the OAuth 2.0 Device Authorization Grant.

1. Send a POST request to http(s)://HOSTNAME/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 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.

2. GitHub will give a response that includes the following query 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: http(s)://HOSTNAME/login/device.
   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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/login/device.

   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 http(s)://HOSTNAME/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 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.
   repository_id	string	The ID of a single repository that the user access token can access. If the GitHub App or user cannot access the repository, this will be ignored. Use this parameter to restrict the access of the user access token further.

   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.

   Until the user enters the code, GitHub 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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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.

5. Once the user has entered the user_code, GitHub will give a response that includes the following query parameters:

   Response parameter	Type	Description
   access_token	string	The user access token. The token starts with ghu_.
   expires_in	integer	The number of seconds until access_token expires. If you disabled expiration of user access tokens, this parameter will be omitted. The value will always be 28800 (8 hours).
   refresh_token	string	The refresh token. If you disabled expiration of user access tokens, this parameter will be omitted. The token starts with ghr_.
   refresh_token_expires_in	integer	The number of seconds until refresh_token expires. If you disabled expiration of user access tokens, this parameter will be omitted. The value will always be 15811200 (6 months).
   scope	string	The scopes that the token has. This value will always be an empty string. Unlike a traditional OAuth token, the user access token is limited to the permissions that both your app and the user have.
   token_type	string	The type of token. The value will always be bearer.

6. Use the user access token from the previous step to make API requests on behalf of the user. Include the user access token in the Authorization header of an API request. For example:

   curl --request GET \
   --url "http(s)://HOSTNAME/api/v3/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN"

Generating a user access token when a user installs your app

If you select Request user authorization (OAuth) during installation in your app settings, GitHub 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, GitHub will redirect the user to http(s)://HOSTNAME/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, GitHub 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.

3. Exchange the code from the previous step for a user access token by making a POST request to this URL, along with the following query parameters: http(s)://HOSTNAME/login/oauth/access_token

   Query parameter	Type	Description
   client_id	string	Required. The client ID for your 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 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.
   client_secret	string	Required. The client secret for your GitHub App. You can generate a client secret on the settings page for your app.
   code	string	Required. The code you received in the previous step.
   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" when setting up your GitHub App and can't contain any additional parameters.
   repository_id	string	The ID of a single repository that the user access token can access. If the GitHub App or user cannot access the repository, this will be ignored. Use this parameter to restrict the access of the user access token further.

4. GitHub will give a response that includes the following parameters:

   Response parameter	Type	Description
   access_token	string	The user access token. The token starts with ghu_.
   expires_in	integer	The number of seconds until access_token expires. If you disabled expiration of user access tokens, this parameter will be omitted. The value will always be 28800 (8 hours).
   refresh_token	string	The refresh token. If you disabled expiration of user access tokens, this parameter will be omitted. The token starts with ghr_.
   refresh_token_expires_in	integer	The number of seconds until refresh_token expires. If you disabled expiration of user access tokens, this parameter will be omitted. The value will always be 15811200 (6 months).
   scope	string	The scopes that the token has. This value will always be an empty string. Unlike a traditional OAuth token, the user access token is limited to the permissions that both your app and the user have.
   token_type	string	The type of token. The value will always be bearer.

5. Use the user access token from the previous step to make API requests on behalf of the user. Include the user access token in the Authorization header of an API request. For example:

   curl --request GET \
   --url "http(s)://HOSTNAME/api/v3/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN"

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 "Refreshing user access tokens."

GitHub 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 "Activating optional features for GitHub Apps".

Supported endpoints for user access tokens

Check Runs

• Create a check run
• Get a check run
• Update a check run
• List check run annotations
• List check runs in a check suite
• List check runs for a Git reference

Check Suites

• Create a check suite
• Get a check suite
• Rerequest a check suite
• Update repository preferences for check suites
• List check suites for a Git reference

Codes Of Conduct

• Get all codes of conduct
• Get a code of conduct

Deployment Statuses

• List deployment statuses
• Create a deployment status
• Get a deployment status

Deployments

• List deployments
• Create a deployment
• Get a deployment
• Delete a deployment

Events

• List public events for a network of repositories
• List public organization events

Feeds

• Get feeds

Git Blobs

• Create a blob
• Get a blob

Git Commits

• Create a commit
• Get a commit

Git Refs

• Create a reference
• Get a reference
• List matching references
• Update a reference
• Delete a reference

Git Tags

• Create a tag object
• Get a tag

Git Trees

• Create a tree
• Get a tree

Gitignore Templates

• Get all gitignore templates
• Get a gitignore template

Installations

• List repositories accessible to the user access token

Issue Assignees

• Add assignees to an issue
• Remove assignees from an issue

Issue Comments

• List issue comments
• Create an issue comment
• List issue comments for a repository
• Get an issue comment
• Update an issue comment
• Delete an issue comment

Issue Events

• List issue events

Issue Timeline

• List timeline events for an issue

Issues

• List issues assigned to the authenticated user
• List assignees
• Check if a user can be assigned
• List repository issues
• Create an issue
• Get an issue
• Update an issue
• Lock an issue
• Unlock an issue

Labels

• List labels for an issue
• Add labels to an issue
• Set labels for an issue
• Remove all labels from an issue
• Remove a label from an issue
• List labels for a repository
• Create a label
• Get a label
• Update a label
• Delete a label
• Get labels for every issue in a milestone

Licenses

• Get all commonly used licenses
• Get a license

Markdown

• Render a Markdown document
• Render a markdown document in raw mode

Meta

• Meta

Milestones

• List milestones
• Create a milestone
• Get a milestone
• Update a milestone
• Delete a milestone

Organization Hooks

• List organization webhooks
• Create an organization webhook
• Get an organization webhook
• Update an organization webhook
• Delete an organization webhook
• Ping an organization webhook

Organization Members

• List organization members
• Check organization membership for a user
• Remove an organization member
• Get organization membership for a user
• Set organization membership for a user
• Remove organization membership for a user
• List public organization members
• Check public organization membership for a user
• Set public organization membership for the authenticated user
• Remove public organization membership for the authenticated user

Organization Outside Collaborators

• List outside collaborators for an organization
• Convert an organization member to outside collaborator
• Remove outside collaborator from an organization

Organization Pre Receive Hooks

• List pre-receive hooks for an organization
• Get a pre-receive hook for an organization
• Update pre-receive hook enforcement for an organization
• Remove pre-receive hook enforcement for an organization

Organization Team Projects

• List team projects
• Check team permissions for a project
• Add or update team project permissions
• Remove a project from a team

Organization Team Repositories

• List team repositories
• Check team permissions for a repository
• Add or update team repository permissions
• Remove a repository from a team

Organization Teams

• List teams

• Create a team

• Get a team by name

• Update a team

• Delete a team

• List team members

• Get team membership for a user

• Add or update team membership for a user

• Remove team membership for a user

• List child teams

• List teams for the authenticated user

Organizations

• List organizations
• Get an organization
• Update an organization
• List organization memberships for the authenticated user
• Get an organization membership for the authenticated user
• Update an organization membership for the authenticated user
• List organizations for the authenticated user
• List organizations for a user

Project Collaborators

• List project collaborators
• Add project collaborator
• Remove project collaborator
• Get project permission for a user

Projects

• List organization projects
• Create an organization project
• Get a project
• Update a project
• Delete a project
• List project columns
• Create a project column
• Get a project column
• Update a project column
• Delete a project column
• List project cards
• Create a project card
• Move a project column
• Get a project card
• Update a project card
• Delete a project card
• Move a project card
• List repository projects
• Create a repository project

Pull Comments

• List review comments on a pull request
• Create a review comment for a pull request
• List review comments in a repository
• Get a review comment for a pull request
• Update a review comment for a pull request
• Delete a review comment for a pull request

Pull Request Review Events

• Dismiss a review for a pull request
• Submit a review for a pull request

Pull Request Review Requests

• List requested reviewers for a pull request
• Request reviewers for a pull request
• Remove requested reviewers from a pull request

Pull Request Reviews

• List reviews for a pull request
• Create a review for a pull request
• Get a review for a pull request
• Update a review for a pull request
• List comments for a pull request review

Pulls

• List pull requests
• Create a pull request
• Get a pull request
• Update a pull request
• List commits on a pull request
• List pull requests files
• Check if a pull request has been merged
• Merge a pull request (Merge Button)

Reactions

• Delete a reaction
• List reactions for a commit comment
• Create reaction for a commit comment
• List reactions for an issue
• Create reaction for an issue
• List reactions for an issue comment
• Create reaction for an issue comment
• List reactions for a pull request review comment
• Create reaction for a pull request review comment
• List reactions for a team discussion comment
• Create reaction for a team discussion comment
• List reactions for a team discussion
• Create reaction for a team discussion
• Delete a commit comment reaction
• Delete an issue reaction
• Delete a reaction to a commit comment
• Delete a pull request comment reaction
• Delete team discussion reaction
• Delete team discussion comment reaction

Repositories

• List organization repositories
• Create a repository for the authenticated user
• Get a repository
• Update a repository
• Delete a repository
• Compare two commits
• List repository contributors
• List forks
• Create a fork
• List repository languages
• List repository tags
• List repository teams
• Transfer a repository
• List public repositories
• List repositories for the authenticated user
• List repositories for a user
• Create repository using a repository template

Repository Activity

• List stargazers
• List watchers
• List repositories starred by a user
• Check if a repository is starred by the authenticated user
• Star a repository for the authenticated user
• Unstar a repository for the authenticated user
• List repositories watched by a user

Repository Branches

• List branches
• Get a branch
• Get branch protection
• Update branch protection
• Delete branch protection
• Get admin branch protection
• Set admin branch protection
• Delete admin branch protection
• Get pull request review protection
• Update pull request review protection
• Delete pull request review protection
• Get commit signature protection
• Create commit signature protection
• Delete commit signature protection
• Get status checks protection
• Update status check protection
• Remove status check protection
• Get all status check contexts
• Add status check contexts
• Set status check contexts
• Remove status check contexts
• Get access restrictions
• Delete access restrictions
• List teams with access to the protected branch
• Add team access restrictions
• Set team access restrictions
• Remove team access restriction
• List user restrictions of protected branch
• Add user access restrictions
• Set user access restrictions
• Remove user access restrictions
• Merge a branch

Repository Collaborators

• List repository collaborators
• Check if a user is a repository collaborator
• Add a repository collaborator
• Remove a repository collaborator
• Get repository permissions for a user

Repository Commit Comments

• List commit comments for a repository
• Get a commit comment
• Update a commit comment
• Delete a commit comment
• List commit comments
• Create a commit comment

Repository Commits

• List commits
• Get a commit
• List branches for head commit
• List pull requests associated with commit

Repository Community

• Get the code of conduct for a repository

Repository Contents

• Download a repository archive
• Get repository content
• Create or update file contents
• Delete a file
• Get a repository README
• Get the license for a repository

Repository Event Dispatches

• Create a repository dispatch event

Repository Hooks

• List repository webhooks
• Create a repository webhook
• Get a repository webhook
• Update a repository webhook
• Delete a repository webhook
• Ping a repository webhook
• Test the push repository webhook

Repository Invitations

• List repository invitations
• Update a repository invitation
• Delete a repository invitation
• List repository invitations for the authenticated user
• Accept a repository invitation
• Decline a repository invitation

Repository Keys

• List deploy keys
• Create a deploy key
• Get a deploy key
• Delete a deploy key

Repository Pages

• Get a GitHub Pages site
• Create a GitHub Pages site
• Update information about a GitHub Pages site
• Delete a GitHub Pages site
• List GitHub Pages builds
• Request a GitHub Pages build
• Get GitHub Pages build
• Get latest pages build

Repository Pre Receive Hooks

• List pre-receive hooks for a repository
• Get a pre-receive hook for a repository
• Update pre-receive hook enforcement for a repository
• Remove pre-receive hook enforcement for a repository

Repository Releases

• List releases
• Create a release
• Get a release
• Update a release
• Delete a release
• List release assets
• Get a release asset
• Update a release asset
• Delete a release asset
• Get the latest release
• Get a release by tag name

Repository Stats

• Get the weekly commit activity
• Get the last year of commit activity
• Get all contributor commit activity
• Get the weekly commit count
• Get the hourly commit count for each day

Root

• Root endpoint
• Emojis
• Get rate limit status for the authenticated user

Search

• Search code
• Search commits
• Search labels
• Search repositories
• Search topics
• Search users

Statuses

• Get the combined status for a specific reference
• List commit statuses for a reference
• Create a commit status

Team Discussions

• List discussions
• Create a discussion
• Get a discussion
• Update a discussion
• Delete a discussion
• List discussion comments
• Create a discussion comment
• Get a discussion comment
• Update a discussion comment
• Delete a discussion comment

Topics

• Get all repository topics
• Replace all repository topics

User Emails

• List email addresses for the authenticated user
• Add email address(es)
• Delete email address(es)
• List public email addresses for the authenticated user

User Followers

• List followers of a user
• List the people a user follows
• Check if a person is followed by the authenticated user
• Follow a user
• Unfollow a user
• Check if a user follows another user

User Gpg Keys

• List GPG keys for the authenticated user
• Create a GPG key for the authenticated user
• Get a GPG key for the authenticated user
• Delete a GPG key for the authenticated user
• List gpg keys for a user

User Public Keys

• List public SSH keys for the authenticated user
• Create a public SSH key for the authenticated user
• Get a public SSH key for the authenticated user
• Delete a public SSH key for the authenticated user
• List public keys for a user

Users

• Get the authenticated user

• List app installations accessible to the user access token

• List users

• Get a user