@github/openapi

{ "openapi": "3.0.1", "info": { "version": "api.github.com", "title": "GitHub REST API", "description": "# Introduction\n\nThis describes the resources that make up the official GitHub REST API v3. If you have any problems or requests, please contact [GitHub Support](https://github.com/contact).", "license": { "name": "MIT" }, "termsOfService": "https://docs.github.com/articles/github-terms-of-service/", "contact": { "name": "Support", "email": "support@github.com" } }, "servers": [ { "url": "https://api.github.com" } ], "externalDocs": { "description": "GitHub v3 REST API", "url": "https://developer.github.com/v3/" }, "paths": { "/app": { "get": { "summary": "Get the authenticated app", "description": "Returns the GitHub App associated with the authentication credentials used. To see how many app installations are associated with this GitHub App, see the `installations_count` in the response. For more details about your app's installations, see the \"[List installations for the authenticated app](https://developer.github.com/v3/apps/#list-installations-for-the-authenticated-app)\" endpoint.\n\nYou must use a [JWT](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.", "operationId": "apps/get-authenticated", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/#get-the-authenticated-app" }, "parameters": [ { "$ref": "#/components/parameters/accept" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/installed_integration" }, "examples": { "default": { "$ref": "#/components/examples/installed_integration" } } } } } }, "x-github": { "enabledForApps": true, "githubCloudOnly": false, "previews": [], "category": "apps" } } }, "/app-manifests/{code}/conversions": { "post": { "summary": "Create a GitHub App from a manifest", "description": "Use this endpoint to complete the handshake necessary when implementing the [GitHub App Manifest flow](https://developer.github.com/apps/building-github-apps/creating-github-apps-from-a-manifest/). When you create a GitHub App with the manifest flow, you receive a temporary `code` used to retrieve the GitHub App's `id`, `pem` (private key), and `webhook_secret`.", "operationId": "apps/create-from-manifest", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/#create-a-github-app-from-a-manifest" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/code" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/integration-from-manifest" }, "examples": { "default": { "$ref": "#/components/examples/integration-from-manifest" } } } } } }, "x-github": { "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps" } } }, "/app/installations": { "get": { "summary": "List installations for the authenticated app", "description": "You must use a [JWT](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.\n\nThe permissions the installation has are included under the `permissions` key.", "operationId": "apps/list-installations", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/#list-installations-for-the-authenticated-app" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "The permissions the installation has are included under the `permissions` key.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/base-installation" } }, "examples": { "default": { "$ref": "#/components/examples/base-installation-items" } } } }, "headers": { "Link": { "$ref": "#/components/headers/Link" } } } }, "x-github": { "enabledForApps": true, "githubCloudOnly": false, "previews": [], "category": "apps" } } }, "/app/installations/{installation_id}": { "get": { "summary": "Get an installation for the authenticated app", "description": "Enables an authenticated GitHub App to find an installation's information using the installation id. The installation's account type (`target_type`) will be either an organization or a user account, depending which account the repository belongs to.\n\nYou must use a [JWT](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.", "operationId": "apps/get-installation", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/#get-an-installation-for-the-authenticated-app" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/installation_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/base-installation" }, "examples": { "default": { "$ref": "#/components/examples/base-installation" } } } } } }, "x-github": { "enabledForApps": true, "githubCloudOnly": false, "previews": [], "category": "apps" } }, "delete": { "summary": "Delete an installation for the authenticated app", "description": "Uninstalls a GitHub App on a user, organization, or business account. If you prefer to temporarily suspend an app's access to your account's resources, then we recommend the \"[Suspend an app installation](https://developer.github.com/v3/apps/#suspend-an-app-installation)\" endpoint.\n\nYou must use a [JWT](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.", "operationId": "apps/delete-installation", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/#delete-an-installation-for-the-authenticated-app" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/installation_id" } ], "responses": { "204": { "description": "Empty response" } }, "x-github": { "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps" } } }, "/app/installations/{installation_id}/access_tokens": { "post": { "summary": "Create an installation access token for an app", "description": "Creates an installation access token that enables a GitHub App to make authenticated API requests for the app's installation on an organization or individual account. Installation tokens expire one hour from the time you create them. Using an expired token produces a status code of `401 - Unauthorized`, and requires creating a new installation token. By default the installation token has access to all repositories that the installation can access. To restrict the access to specific repositories, you can provide the `repository_ids` when creating the token. When you omit `repository_ids`, the response does not contain the `repositories` key.\n\nYou must use a [JWT](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.", "operationId": "apps/create-installation-access-token", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/#create-an-installation-access-token-for-an-app" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/installation_id" } ], "responses": { "201": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/installation-token" }, "examples": { "default": { "$ref": "#/components/examples/installation-token" } } } } } }, "x-github": { "enabledForApps": true, "githubCloudOnly": false, "previews": [], "category": "apps" }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "repository_ids": { "type": "array", "description": "The `id`s of the repositories that the installation token can access. Providing repository `id`s restricts the access of an installation token to specific repositories. You can use the \"[List repositories accessible to the app installation](https://developer.github.com/v3/apps/installations/#list-repositories-accessible-to-the-app-installation)\" endpoint to get the `id` of all repositories that an installation can access. For example, you can select specific repositories when creating an installation token to restrict the number of repositories that can be cloned using the token.", "items": { "type": "integer" } }, "permissions": { "type": "object", "description": "The permissions granted to the access token. The permissions object includes the permission names and their access type. For a complete list of permissions and allowable values, see \"[GitHub App permissions](https://developer.github.com/apps/building-github-apps/creating-github-apps-using-url-parameters/#github-app-permissions).\"", "properties": {}, "additionalProperties": true } } }, "example": { "repository_ids": [ 1296269 ], "permissions": { "issues": "write", "contents": "read" } } } } }, "x-githubBreakingChanges": [ { "type": "operation", "date": "2020-06-04", "note": "\"apps/create-installation-token\" operation ID is now \"apps/create-installation-access-token\"", "before": { "operationId": "apps/create-installation-token" }, "after": { "operationId": "apps/create-installation-access-token" } } ] } }, "/app/installations/{installation_id}/suspended": { "put": { "summary": "Suspend an app installation", "description": "**Note:** Suspending a GitHub App installation is currently in beta and subject to change. Before you can suspend a GitHub App, the app owner must enable suspending installations for the app by opting-in to the beta. For more information, see \"[Suspending a GitHub App installation](https://developer.github.com/apps/managing-github-apps/suspending-a-github-app-installation/).\"\n\nSuspends a GitHub App on a user, organization, or business account, which blocks the app from accessing the account's resources. When a GitHub App is suspended, the app's access to the GitHub API or webhook events is blocked for that account.\n\nTo suspend a GitHub App, you must be an account owner or have admin permissions in the repository or organization where the app is installed.\n\nYou must use a [JWT](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.", "operationId": "apps/suspend-installation", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/#suspend-an-app-installation" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/installation_id" } ], "responses": { "204": { "description": "Empty response" } }, "x-github": { "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps" } }, "delete": { "summary": "Unsuspend an app installation", "description": "**Note:** Suspending a GitHub App installation is currently in beta and subject to change. Before you can suspend a GitHub App, the app owner must enable suspending installations for the app by opting-in to the beta. For more information, see \"[Suspending a GitHub App installation](https://developer.github.com/apps/managing-github-apps/suspending-a-github-app-installation/).\"\n\nRemoves a GitHub App installation suspension.\n\nTo unsuspend a GitHub App, you must be an account owner or have admin permissions in the repository or organization where the app is installed and suspended.\n\nYou must use a [JWT](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.", "operationId": "apps/unsuspend-installation", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/#unsuspend-an-app-installation" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/installation_id" } ], "responses": { "204": { "description": "Empty response" } }, "x-github": { "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps" } } }, "/applications/grants": { "get": { "summary": "List your grants", "description": "**Deprecation Notice:** GitHub will discontinue the [OAuth Authorizations API](https://developer.github.com/v3/oauth_authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). The [OAuth Authorizations API](https://developer.github.com/v3/oauth_authorizations/) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).\n\nYou can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the [list your authorizations](https://developer.github.com/v3/oauth_authorizations/#list-your-authorizations) API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on [the application authorizations settings screen within GitHub](https://github.com/settings/applications#authorized). The `scopes` returned are the union of scopes authorized for the application. For example, if an application has one token with `repo` scope and another token with `user` scope, the grant will return `[\"repo\", \"user\"]`.", "operationId": "oauth-authorizations/list-grants", "tags": [ "oauth-authorizations" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/oauth_authorizations/#list-your-grants" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/application-grant" } }, "examples": { "default": { "$ref": "#/components/examples/application-grant-items" } } } }, "headers": { "Link": { "$ref": "#/components/headers/Link" } } } }, "x-github": { "deprecationDate": "2020-02-14", "removalDate": "2020-11-13", "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "oauth-authorizations" }, "deprecated": true } }, "/applications/grants/{grant_id}": { "get": { "summary": "Get a single grant", "description": "**Deprecation Notice:** GitHub will discontinue the [OAuth Authorizations API](https://developer.github.com/v3/oauth_authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). The [OAuth Authorizations API](https://developer.github.com/v3/oauth_authorizations/) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).", "operationId": "oauth-authorizations/get-grant", "tags": [ "oauth-authorizations" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/oauth_authorizations/#get-a-single-grant" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/grant_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/application-grant" }, "examples": { "default": { "$ref": "#/components/examples/application-grant" } } } } } }, "x-github": { "deprecationDate": "2020-02-14", "removalDate": "2020-11-13", "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "oauth-authorizations" }, "deprecated": true }, "delete": { "summary": "Delete a grant", "description": "**Deprecation Notice:** GitHub will discontinue the [OAuth Authorizations API](https://developer.github.com/v3/oauth_authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). The [OAuth Authorizations API](https://developer.github.com/v3/oauth_authorizations/) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).\n\nDeleting an OAuth application's grant will also delete all OAuth tokens associated with the application for your user. Once deleted, the application has no access to your account and is no longer listed on [the application authorizations settings screen within GitHub](https://github.com/settings/applications#authorized).", "operationId": "oauth-authorizations/delete-grant", "tags": [ "oauth-authorizations" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/oauth_authorizations/#delete-a-grant" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/grant_id" } ], "responses": { "204": { "description": "Empty response" } }, "x-github": { "deprecationDate": "2020-02-14", "removalDate": "2020-11-13", "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "oauth-authorizations" }, "deprecated": true } }, "/applications/{client_id}/grant": { "delete": { "summary": "Delete an app authorization", "description": "OAuth application owners can revoke a grant for their OAuth application and a specific user. You must use [Basic Authentication](https://developer.github.com/v3/auth#basic-authentication) when accessing this endpoint, using the OAuth application's `client_id` and `client_secret` as the username and password. You must also provide a valid OAuth `access_token` as an input parameter and the grant for the token's owner will be deleted.\n\nDeleting an OAuth application's grant will also delete all OAuth tokens associated with the application for the user. Once deleted, the application will have no access to the user's account and will no longer be listed on [the application authorizations settings screen within GitHub](https://github.com/settings/applications#authorized).", "operationId": "apps/delete-authorization", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/oauth_applications/#delete-an-app-authorization" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/client_id" } ], "responses": { "204": { "description": "Empty response" } }, "x-github": { "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps", "subcategory": "oauth-applications" }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The OAuth access token used to authenticate to the GitHub API." } } }, "example": { "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a" } } } } } }, "/applications/{client_id}/grants/{access_token}": { "delete": { "summary": "Revoke a grant for an application", "description": "**Deprecation Notice:** GitHub will replace and discontinue OAuth endpoints containing `access_token` in the path parameter. We are introducing new endpoints that allow you to securely manage tokens for OAuth Apps by using `access_token` as an input parameter. The OAuth Application API will be removed on May 5, 2021. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-app-endpoint/).\n\nOAuth application owners can revoke a grant for their OAuth application and a specific user. You must use [Basic Authentication](https://developer.github.com/v3/auth#basic-authentication) when accessing this endpoint, using the OAuth application's `client_id` and `client_secret` as the username and password. You must also provide a valid token as `:access_token` and the grant for the token's owner will be deleted.\n\nDeleting an OAuth application's grant will also delete all OAuth tokens associated with the application for the user. Once deleted, the application will have no access to the user's account and will no longer be listed on [the Applications settings page under \"Authorized OAuth Apps\" on GitHub](https://github.com/settings/applications#authorized).", "operationId": "apps/revoke-grant-for-application", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/oauth_applications/#revoke-a-grant-for-an-application" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/client_id" }, { "$ref": "#/components/parameters/access_token" } ], "responses": { "204": { "description": "Empty response" } }, "x-github": { "deprecationDate": "2020-02-14", "removalDate": "2021-05-05", "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps", "subcategory": "oauth-applications" }, "deprecated": true, "x-githubBreakingChanges": [ { "type": "operation", "date": "2019-11-05", "note": "\"Revoke a grant for an application\" has been moved from \"OAuth Authorizations\" to \"Apps\"", "before": { "operationId": "oauth-authorizations/revoke-grant-for-application" }, "after": { "operationId": "apps/revoke-grant-for-application" } } ] } }, "/applications/{client_id}/token": { "post": { "summary": "Check a token", "description": "OAuth applications can use a special API method for checking OAuth token validity without exceeding the normal rate limits for failed login attempts. Authentication works differently with this particular endpoint. You must use [Basic Authentication](https://developer.github.com/v3/auth#basic-authentication) to use this endpoint, where the username is the OAuth application `client_id` and the password is its `client_secret`. Invalid tokens will return `404 NOT FOUND`.", "operationId": "apps/check-token", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/oauth_applications/#check-a-token" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/client_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authorization-with-user" }, "examples": { "default": { "$ref": "#/components/examples/authorization-with-user" } } } } } }, "x-github": { "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps", "subcategory": "oauth-applications" }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The OAuth access token used to authenticate to the GitHub API." } } }, "example": { "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a" } } } } }, "patch": { "summary": "Reset a token", "description": "OAuth applications can use this API method to reset a valid OAuth token without end-user involvement. Applications must save the \"token\" property in the response because changes take effect immediately. You must use [Basic Authentication](https://developer.github.com/v3/auth#basic-authentication) when accessing this endpoint, using the OAuth application's `client_id` and `client_secret` as the username and password. Invalid tokens will return `404 NOT FOUND`.", "operationId": "apps/reset-token", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/oauth_applications/#reset-a-token" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/client_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authorization-with-user" }, "examples": { "default": { "$ref": "#/components/examples/authorization-with-user" } } } } } }, "x-github": { "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps", "subcategory": "oauth-applications" }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The OAuth access token used to authenticate to the GitHub API." } } }, "example": { "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a" } } } } }, "delete": { "summary": "Delete an app token", "description": "OAuth application owners can revoke a single token for an OAuth application. You must use [Basic Authentication](https://developer.github.com/v3/auth#basic-authentication) when accessing this endpoint, using the OAuth application's `client_id` and `client_secret` as the username and password.", "operationId": "apps/delete-token", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/oauth_applications/#delete-an-app-token" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/client_id" } ], "responses": { "204": { "description": "Empty response" } }, "x-github": { "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps", "subcategory": "oauth-applications" }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The OAuth access token used to authenticate to the GitHub API." } } }, "example": { "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a" } } } } } }, "/applications/{client_id}/tokens/{access_token}": { "get": { "summary": "Check an authorization", "description": "**Deprecation Notice:** GitHub will replace and discontinue OAuth endpoints containing `access_token` in the path parameter. We are introducing new endpoints that allow you to securely manage tokens for OAuth Apps by using `access_token` as an input parameter. The OAuth Application API will be removed on May 5, 2021. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-app-endpoint/).\n\nOAuth applications can use a special API method for checking OAuth token validity without exceeding the normal rate limits for failed login attempts. Authentication works differently with this particular endpoint. You must use [Basic Authentication](https://developer.github.com/v3/auth#basic-authentication) when accessing this endpoint, using the OAuth application's `client_id` and `client_secret` as the username and password. Invalid tokens will return `404 NOT FOUND`.", "operationId": "apps/check-authorization", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/oauth_applications/#check-an-authorization" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/client_id" }, { "$ref": "#/components/parameters/access_token" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authorization-with-user" }, "examples": { "default": { "$ref": "#/components/examples/authorization-with-user" } } } } } }, "x-github": { "deprecationDate": "2020-02-14", "removalDate": "2021-05-05", "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps", "subcategory": "oauth-applications" }, "deprecated": true, "x-githubBreakingChanges": [ { "type": "operation", "date": "2019-11-05", "note": "\"Check an authorization\" has been moved from \"OAuth Authorizations\" to \"Apps\"", "before": { "operationId": "oauth-authorizations/check-authorization" }, "after": { "operationId": "apps/check-authorization" } } ] }, "post": { "summary": "Reset an authorization", "description": "**Deprecation Notice:** GitHub will replace and discontinue OAuth endpoints containing `access_token` in the path parameter. We are introducing new endpoints that allow you to securely manage tokens for OAuth Apps by using `access_token` as an input parameter. The OAuth Application API will be removed on May 5, 2021. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-app-endpoint/).\n\nOAuth applications can use this API method to reset a valid OAuth token without end-user involvement. Applications must save the \"token\" property in the response because changes take effect immediately. You must use [Basic Authentication](https://developer.github.com/v3/auth#basic-authentication) when accessing this endpoint, using the OAuth application's `client_id` and `client_secret` as the username and password. Invalid tokens will return `404 NOT FOUND`.", "operationId": "apps/reset-authorization", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/oauth_applications/#reset-an-authorization" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/client_id" }, { "$ref": "#/components/parameters/access_token" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authorization-with-user" }, "examples": { "default": { "$ref": "#/components/examples/authorization-with-user" } } } } } }, "x-github": { "deprecationDate": "2020-02-14", "removalDate": "2021-05-05", "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps", "subcategory": "oauth-applications" }, "deprecated": true, "x-githubBreakingChanges": [ { "type": "operation", "date": "2019-11-05", "note": "\"Reset an authorization\" has been moved from \"OAuth Authorizations\" to \"Apps\"", "before": { "operationId": "oauth-authorizations/reset-authorization" }, "after": { "operationId": "apps/reset-authorization" } } ] }, "delete": { "summary": "Revoke an authorization for an application", "description": "**Deprecation Notice:** GitHub will replace and discontinue OAuth endpoints containing `access_token` in the path parameter. We are introducing new endpoints that allow you to securely manage tokens for OAuth Apps by using `access_token` as an input parameter. The OAuth Application API will be removed on May 5, 2021. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-app-endpoint/).\n\nOAuth application owners can revoke a single token for an OAuth application. You must use [Basic Authentication](https://developer.github.com/v3/auth#basic-authentication) when accessing this endpoint, using the OAuth application's `client_id` and `client_secret` as the username and password.", "operationId": "apps/revoke-authorization-for-application", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/oauth_applications/#revoke-an-authorization-for-an-application" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/client_id" }, { "$ref": "#/components/parameters/access_token" } ], "responses": { "204": { "description": "Empty response" } }, "x-github": { "deprecationDate": "2020-02-14", "removalDate": "2021-05-05", "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "apps", "subcategory": "oauth-applications" }, "deprecated": true, "x-githubBreakingChanges": [ { "type": "operation", "date": "2019-11-05", "note": "\"Revoke an authorization for an application\" has been moved from \"OAuth Authorizations\" to \"Apps\"", "before": { "operationId": "oauth-authorizations/revoke-authorization-for-application" }, "after": { "operationId": "apps/revoke-authorization-for-application" } } ] } }, "/apps/{app_slug}": { "get": { "summary": "Get an app", "description": "**Note**: The `:app_slug` is just the URL-friendly name of your GitHub App. You can find this on the settings page for your GitHub App (e.g., `https://github.com/settings/apps/:app_slug`).\n\nIf the GitHub App you specify is public, you can access this endpoint without authenticating. If the GitHub App you specify is private, you must authenticate with a [personal access token](https://docs.github.com/articles/creating-a-personal-access-token-for-the-command-line/) or an [installation access token](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation) to access this endpoint.", "operationId": "apps/get-by-slug", "tags": [ "apps" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/apps/#get-an-app" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/app_slug" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/integration" }, "examples": { "default": { "$ref": "#/components/examples/integration" } } } } } }, "x-github": { "enabledForApps": true, "githubCloudOnly": false, "previews": [], "category": "apps" } } }, "/authorizations": { "get": { "summary": "List your authorizations", "description": "**Deprecation Notice:** GitHub will discontinue the [OAuth Authorizations API](https://developer.github.com/v3/oauth_authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). The [OAuth Authorizations API](https://developer.github.com/v3/oauth_authorizations/) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).", "operationId": "oauth-authorizations/list-authorizations", "tags": [ "oauth-authorizations" ], "externalDocs": { "description": "API method documentation", "url": "https://developer.github.com/v3/oauth_authorizations/#list-your-authorizations" }, "parameters": [ { "$ref": "#/components/parameters/accept" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/authorization" } }, "examples": { "default": { "$ref": "#/components/examples/authorization-items" } } } }, "headers": { "Link": { "$ref": "#/components/headers/Link" } } } }, "x-github": { "deprecationDate": "2020-02-14", "removalDate": "2020-11-13", "enabledForApps": false, "githubCloudOnly": false, "previews": [], "category": "oauth-authorizations" }, "deprecated": true }, "post": { "summary": "Create a new authorization", "description": "**Deprecation Notice:** GitHub will discontinue the [OAuth Authorizations API](https://developer.github.com/v3/oauth_authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). The [OAuth Authorizations API](https://developer.github.com/v3/oauth_authorizations/) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).\n\n**Warning:** Apps must use the [web application flow](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow) to obtain OAuth tokens that work with GitHub SAML organizations. OAuth tokens created using the Authorizations API will be unable to access GitHub SAML organizations. For more information, see the [blog post](https://developer.github.com/changes/2019-11-05-deprecated-passwords-and-authorizations-api).\n\nCreates OAuth tokens using [Basic Authentication](https://developer.github.com/v3/auth#basic-authentication). If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see \"[Working with two-factor authentication](https://developer.github.com/v3/auth/#working-with-two-factor-authentication).\"\n\nTo create tokens for a particular OAuth application using this endpoint, you must authenticate as the user you want to create an authorization for and provide the app's client ID and secret, found on your OAuth application's settings page. If your OAuth application