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.
Identifying users on your site
To authorize users for standard apps that run in the browser, use the web application flow.
Web アプリケーションフロー
Using the web application flow, the process to identify users on your site is:
- ユーザはGitHubのアイデンティティをリクエストするためにリダイレクトされます
- ユーザはGitHubによってサイトにリダイレクトして戻されます
- 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. ユーザのGitHubアイデンティティのリクエスト
GET http(s)://[hostname]/login/oauth/authorize
GitHub Appがloginパラメータを指定すると、ユーザに対して利用できる特定のアカウントでサインインしてアプリケーションを認可するよう求めます。
パラメータ
| 名前 | 種類 | 説明 |
|---|---|---|
client_id | string | Required. The client ID for your GitHub App. You can find this in your GitHub App settings when you select your app. |
redirect_uri | string | 認可の後にユーザが送られるアプリケーション中のURL。 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. |
state | string | This should contain a random string to protect against forgery attacks and could contain any other arbitrary data. |
login | string | サインインとアプリケーションの認可に使われるアカウントを指示します。 |
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. ユーザは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.
POST http(s)://[hostname]/login/oauth/access_token
パラメータ
| 名前 | 種類 | 説明 |
|---|---|---|
client_id | string | Required. The client ID for your GitHub App. |
client_secret | string | Required. The client secret for your GitHub App. |
コード | string | 必須。 ステップ1でレスポンスとして受け取ったコード。 |
redirect_uri | string | 認可の後にユーザが送られるアプリケーション中のURL。 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. |
state | string | ステップ1で提供した推測できないランダムな文字列。 |
レスポンス
デフォルトでは、レスポンスは以下の形式になります。
access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&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
たとえば、curlでは以下のようにAuthorizationヘッダを設定できます。
curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/userCheck which installation's resources a user can access
Note: To access the API with your GitHub App, you must provide a custom media type in the Accept Header for your requests.
application/vnd.github.machine-man-preview+json
Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact your site administrator.
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
チェックラン
- 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
チェックスイート
- 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
Deployment Statuses
デプロイメント
イベント
フィード
Git Blobs
Git Commits
Git Refs
Git Tags
Git Trees
Gitignore Templates
Installations
Issue Assignees
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
Issue Timeline
問題
- List issues assigned to the authenticated user
- List assignees
- Check if a user can be assigned
- List repository issues
- Issue を作成します
- Get an issue
- Update an issue
- Lock an issue
- Unlock an issue
ラベル
- 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
ライセンス
Markdown
メタ情報
マイルストーン
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 Repositories
- Team リポジトリの一覧表示
- Check team permissions for a repository
- Add or update team repository permissions
- Remove a repository from a team
Organization Teams
Organization
- 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
プロジェクト
- 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
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)
リアクション
- 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
リポジトリ
- Organization リポジトリの一覧表示
- Create a repository for the authenticated user
- リポジトリの Get
- Update a repository
- Delete a repository
- Compare two commits
- List repository contributors
- 一覧表示のフォーク
- Create a fork
- List repository languages
- List repository tags
- List repository teams
- Transfer a repository
- List public repositories
- List repositories for the authenticated 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
- ユーザが Watch しているリポジトリの一覧表示
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
Repository Community
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 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
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
- リリースの一覧表示
- Create a release
- Get 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
ルート
検索
ステータス
- 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
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