diff --git a/content/actions/security-guides/automatic-token-authentication.md b/content/actions/security-guides/automatic-token-authentication.md index 286b430d7c0d..4adb4d82c565 100644 --- a/content/actions/security-guides/automatic-token-authentication.md +++ b/content/actions/security-guides/automatic-token-authentication.md @@ -137,3 +137,7 @@ If you need a token that requires permissions that aren't available in the `GITH 1. Use or create a token with the appropriate permissions for that repository. For more information, see "[Creating a personal access token](/github/authenticating-to-github/creating-a-personal-access-token)." 1. Add the token as a secret in your workflow's repository, and refer to it using the {%raw%}`${{ secrets.SECRET_NAME }}`{% endraw %} syntax. For more information, see "[Creating and using encrypted secrets](/github/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." + +### Further reading + +- "[Resources in the REST API](/rest/overview/resources-in-the-rest-api#rate-limiting)" diff --git a/content/developers/apps/building-github-apps/rate-limits-for-github-apps.md b/content/developers/apps/building-github-apps/rate-limits-for-github-apps.md index 6027f1bb2b54..ad392b6ee1a5 100644 --- a/content/developers/apps/building-github-apps/rate-limits-for-github-apps.md +++ b/content/developers/apps/building-github-apps/rate-limits-for-github-apps.md @@ -16,46 +16,70 @@ topics: - GitHub Apps shortTitle: Rate limits --- -## Server-to-server requests -{% ifversion ghec %} +{% data reusables.enterprise.rate_limit %} + +{% data reusables.rest-api.always-check-your-limit %} -The rate limits for server-to-server requests made by {% data variables.product.prodname_github_apps %} depend on where the app is installed. If the app is installed on organizations or repositories owned by an enterprise on {% data variables.product.product_location %}, then the rate is higher than for installations outside an enterprise. +{% ifversion ghec or fpt %} -### Normal server-to-server rate limits +## About rate limits for apps + +Rate limits for {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} depend on the plan for the organization where you install the application. For more information, see "[{% data variables.product.company_short %}'s products](/get-started/learning-about-github/githubs-products)" and "[Types of {% data variables.product.company_short %} accounts](/get-started/learning-about-github/types-of-github-accounts#organization-accounts)." {% endif %} -{% data reusables.apps.api-rate-limits-non-ghec %} +## Server-to-server requests -{% ifversion ghec %} +{% ifversion ghec or fpt %} + +### Default server-to-server rate limits for {% data variables.product.prodname_dotcom_the_website %} + +{% endif %} + +{% data variables.product.prodname_github_apps %} making server-to-server requests use the installation's minimum rate limit of 5,000 requests per hour. If an application is installed on an organization with more than 20 users, the application receives another 50 requests per hour for each user. Installations that have more than 20 repositories receive another 50 requests per hour for each repository. The maximum rate limit for an installation is 12,500 requests per hour. + +{% ifversion fpt or ghec %} -### {% data variables.product.prodname_ghe_cloud %} server-to-server rate limits +### Server-to-server rate limits for {% data variables.product.prodname_ghe_cloud %} -{% data variables.product.prodname_github_apps %} that are installed on an organization or repository owned by an enterprise on {% data variables.product.product_location %} have a rate limit of 15,000 requests per hour for server-to-server requests. +{% endif %} + +{% ifversion fpt or ghec %} + +{% data variables.product.prodname_github_apps %} that are installed on an organization or a repository within an enterprise on {% data variables.product.product_location %} are subject to a limit of 15,000 requests per hour. {% endif %} ## User-to-server requests -{% data variables.product.prodname_github_apps %} can also act [on behalf of a user](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#identifying-and-authorizing-users-for-github-apps), making user-to-server requests. +{% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} can also act on behalf of a user, making user-to-server requests after the user authorizes the app. For more information, see "[Authorizing {% data variables.product.prodname_github_apps %}](/authentication/keeping-your-account-and-data-secure/authorizing-github-apps)" and "[Authorizing {% data variables.product.prodname_oauth_apps %}](/authentication/keeping-your-account-and-data-secure/authorizing-oauth-apps)." + +User-to-server requests from {% data variables.product.prodname_oauth_apps %} are authenticated with an OAuth token. User-to-server requests from {% data variables.product.prodname_github_apps %} are authenticated with either an OAuth token or an expiring user access token. For more information, see "[Identifying and authorizing users for {% data variables.product.prodname_github_apps %}](/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps#identifying-and-authorizing-users-for-github-apps)" and "[Authorizing {% data variables.product.prodname_oauth_apps %}](/developers/apps/building-oauth-apps/authorizing-oauth-apps)." + +{% ifversion fpt or ghec %} + +### Default user-to-server rate limits for {% data variables.product.prodname_dotcom_the_website %} + +{% endif %} {% ifversion ghec %} The rate limits for user-to-server requests made by {% data variables.product.prodname_github_apps %} depend on where the app is installed. If the app is installed on organizations or repositories owned by an enterprise on {% data variables.product.product_location %}, then the rate is higher than for installations outside an enterprise. -### Normal user-to-server rate limits - {% endif %} -User-to-server requests are rate limited at {% ifversion ghae %}15,000{% else %}5,000{% endif %} requests per hour and per authenticated user. All OAuth applications authorized by that user, personal access tokens owned by that user, and requests authenticated with that user's{% ifversion ghae %} token{% else %} username and password{% endif %} share the same quota of 5,000 requests per hour for that user. +{% data reusables.apps.user-to-server-rate-limits %} -{% ifversion ghec %} +{% ifversion fpt or ghec %} -### {% data variables.product.prodname_ghe_cloud %} user-to-server rate limits +### User-to-server rate limits for {% data variables.product.prodname_ghe_cloud %} -When a user belongs to an enterprise on {% data variables.product.product_location %}, user-to-server requests to resources owned by the same enterprise are rate limited at 15,000 requests per hour and per authenticated user. All OAuth applications authorized by that user, personal access tokens owned by that user, and requests authenticated with that user's username and password share the same quota of 5,000 requests per hour for that user. +{% data reusables.apps.user-to-server-rate-limits-ghec %} {% endif %} -For more detailed information about rate limits, see "[Rate limiting](/rest/overview/resources-in-the-rest-api#rate-limiting)" for REST API and "[Resource limitations]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql/overview/resource-limitations)" for GraphQL API. +## Further reading + +- "[Rate limiting](/rest/overview/resources-in-the-rest-api#rate-limiting)" in the REST API documentation +- "[Resource limitations]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql/overview/resource-limitations)" in the GraphQL API documentation diff --git a/content/developers/apps/getting-started-with-apps/differences-between-github-apps-and-oauth-apps.md b/content/developers/apps/getting-started-with-apps/differences-between-github-apps-and-oauth-apps.md index 6e2ffa00baa1..6006aba79cf5 100644 --- a/content/developers/apps/getting-started-with-apps/differences-between-github-apps-and-oauth-apps.md +++ b/content/developers/apps/getting-started-with-apps/differences-between-github-apps-and-oauth-apps.md @@ -61,9 +61,9 @@ An _authorized_ OAuth App has access to all of the user's or organization owner' | A GitHub App can request an installation access token by using a private key with a JSON web token format out-of-band. | An OAuth app can exchange a request token for an access token after a redirect via a web request. | | An installation token identifies the app as the GitHub Apps bot, such as @jenkins-bot. | An access token identifies the app as the user who granted the token to the app, such as @octocat. | | Installation tokens expire after a predefined amount of time (currently 1 hour). | OAuth tokens remain active until they're revoked by the customer. | -| {% data reusables.apps.api-rate-limits-non-ghec %}{% ifversion fpt or ghec %} Higher rate limits apply for {% data variables.product.prodname_ghe_cloud %}. For more information, see "[Rate limits for GitHub Apps](/developers/apps/rate-limits-for-github-apps)."{% endif %} | OAuth tokens use the user's rate limit of 5,000 requests per hour. | +| {% data variables.product.prodname_github_apps %} installed on organizations or repositories are subject to rate limits for server-to-server requests. For more information, see "[Rate limits for {% data variables.product.prodname_github_apps %}](/developers/apps/building-github-apps/rate-limits-for-github-apps)." | OAuth tokens use the user's rate limit of {% ifversion fpt or ghec or ghes %}5,000{% elsif ghae %}15,000{% endif %} requests per hour. | | Rate limit increases can be granted both at the GitHub Apps level (affecting all installations) and at the individual installation level. | Rate limit increases are granted per OAuth App. Every token granted to that OAuth App gets the increased limit. | -| {% data variables.product.prodname_github_apps %} can authenticate on behalf of the user, which is called user-to-server requests. The flow to authorize is the same as the OAuth App authorization flow. User-to-server tokens can expire and be renewed with a refresh token. For more information, see "[Refreshing user-to-server access tokens](/apps/building-github-apps/refreshing-user-to-server-access-tokens/)" and "[Identifying and authorizing users for GitHub Apps](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/)." | The OAuth flow used by {% data variables.product.prodname_oauth_apps %} authorizes an {% data variables.product.prodname_oauth_app %} on behalf of the user. This is the same flow used in {% data variables.product.prodname_github_app %} user-to-server authorization. | +| {% data variables.product.prodname_github_apps %} can authenticate on behalf of the user, which is called a user-to-server request. The flow to authorize is the same as the OAuth App authorization flow. User-to-server tokens can expire and be renewed with a refresh token. For more information, see "[Refreshing user-to-server access tokens](/apps/building-github-apps/refreshing-user-to-server-access-tokens/)" and "[Identifying and authorizing users for GitHub Apps](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/)." | The OAuth flow used by {% data variables.product.prodname_oauth_apps %} authorizes an {% data variables.product.prodname_oauth_app %} on behalf of the user. This is the same flow used in {% data variables.product.prodname_github_app %} user-to-server authorization. | ## Requesting permission levels for resources diff --git a/content/developers/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md b/content/developers/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md index 8a02a458a71f..fdb03aa53bc6 100644 --- a/content/developers/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md +++ b/content/developers/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md @@ -27,6 +27,6 @@ See these pages for details on how to authenticate when using the {% data variab {% note %} -**Note:** [Rate limits for the REST API](/rest#rate-limiting) apply to all {% data variables.product.prodname_marketplace %} API endpoints. +**Note:** [Rate limits for the REST API](/rest/overview/resources-in-the-rest-api#rate-limiting) apply to all {% data variables.product.prodname_marketplace %} API endpoints. {% endnote %} diff --git a/content/rest/guides/best-practices-for-integrators.md b/content/rest/guides/best-practices-for-integrators.md index 7ad5e448cacf..b444e447d28b 100644 --- a/content/rest/guides/best-practices-for-integrators.md +++ b/content/rest/guides/best-practices-for-integrators.md @@ -131,7 +131,7 @@ end In this example the `closed` action is checked first before calling the `process_closed` method. Any unidentified actions are logged for future reference. -{% ifversion fpt or ghec %} +{% ifversion fpt or ghec or ghae %} ## Dealing with rate limits diff --git a/content/rest/guides/getting-started-with-the-rest-api.md b/content/rest/guides/getting-started-with-the-rest-api.md index 4e6053352c07..bed4173b6b73 100644 --- a/content/rest/guides/getting-started-with-the-rest-api.md +++ b/content/rest/guides/getting-started-with-the-rest-api.md @@ -472,7 +472,7 @@ Keep learning with the next API guide [Basics of Authentication][auth guide]! [issues-api]: /rest/reference/issues [link-header]: https://www.w3.org/wiki/LinkHeader [conditional-requests]: /rest#conditional-requests -[rate-limiting]: /rest#rate-limiting +[rate-limiting]: /rest/overview/resources-in-the-rest-api#rate-limit-http-headers [users api]: /rest/reference/users#get-a-user [auth user api]: /rest/reference/users#get-the-authenticated-user [defunkt github]: https://github.com/defunkt diff --git a/content/rest/overview/resources-in-the-rest-api.md b/content/rest/overview/resources-in-the-rest-api.md index 49c817576803..a909156e4c7b 100644 --- a/content/rest/overview/resources-in-the-rest-api.md +++ b/content/rest/overview/resources-in-the-rest-api.md @@ -8,6 +8,7 @@ versions: ghes: '*' ghae: '*' ghec: '*' +miniTocMaxHeadingLevel: 3 topics: - API --- @@ -123,7 +124,7 @@ Read [more about OAuth2](/apps/building-oauth-apps/). Note that OAuth2 tokens c curl -u my_client_id:my_client_secret '{% data variables.product.api_url_pre %}/user/repos' ``` -Using your `client_id` and `client_secret` does _not_ authenticate as a user, it will only identify your OAuth application to increase your rate limit. Permissions are only granted to users, not applications, and you will only get back data that an unauthenticated user would see. For this reason, you should only use the OAuth2 key/secret in server-to-server scenarios. Don't leak your OAuth application's client secret to your users. +Using your `client_id` and `client_secret` does _not_ authenticate as a user, it will only identify your OAuth App to increase your rate limit. Permissions are only granted to users, not applications, and you will only get back data that an unauthenticated user would see. For this reason, you should only use the OAuth2 key/secret in server-to-server scenarios. Don't leak your OAuth App's client secret to your users. {% ifversion ghes %} You will be unable to authenticate using your OAuth2 key and secret while in private mode, and trying to authenticate will return `401 Unauthorized`. For more information, see "[Enabling private mode](/admin/configuration/configuring-your-enterprise/enabling-private-mode)". @@ -356,21 +357,53 @@ Name | Description ## Rate limiting -For API requests using Basic Authentication or OAuth, you can make up to 5,000 requests per hour. Authenticated requests are associated with the authenticated user, regardless of whether [Basic Authentication](#basic-authentication) or [an OAuth token](#oauth2-token-sent-in-a-header) was used. This means that all OAuth applications authorized by a user share the same quota of 5,000 requests per hour when they authenticate with different tokens owned by the same user. +Different types of API requests to {% data variables.product.product_location %} are subject to different rate limits. + +Additionally, the Search API has dedicated limits. For more information, see "[Search](/rest/reference/search#rate-limit)" in the REST API documentation. + +{% data reusables.enterprise.rate_limit %} + +{% data reusables.rest-api.always-check-your-limit %} + +### Requests from user accounts + +Direct API requests that you authenticate with a personal access token are user-to-server requests. An OAuth App or GitHub App can also make a user-to-server request on your behalf after you authorize the app. For more information, see "[Creating a personal access token](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)," "[Authorizing OAuth Apps](/authentication/keeping-your-account-and-data-secure/authorizing-oauth-apps)," and "[Authorizing GitHub Apps](/authentication/keeping-your-account-and-data-secure/authorizing-github-apps)." + +{% data variables.product.product_name %} associates all user-to-server requests with the authenticated user. For OAuth Apps and GitHub Apps, this is the user who authorized the app. All user-to-server requests count toward the authenticated user's rate limit. + +{% data reusables.apps.user-to-server-rate-limits %} {% ifversion fpt or ghec %} -For users that belong to a {% data variables.product.prodname_ghe_cloud %} account, requests made using an OAuth token to resources owned by the same {% data variables.product.prodname_ghe_cloud %} account have an increased limit of 15,000 requests per hour. +{% data reusables.apps.user-to-server-rate-limits-ghec %} + +{% ifversion fpt or ghec or ghes %} + +For unauthenticated requests, the rate limit allows for up to 60 requests per hour. Unauthenticated requests are associated with the originating IP address, and not the person making requests. {% endif %} -When using the built-in `GITHUB_TOKEN` in GitHub Actions, the rate limit is 1,000 requests per hour per repository. For organizations that belong to a GitHub Enterprise Cloud account, this limit is 15,000 requests per hour per repository. +{% endif %} -For unauthenticated requests, the rate limit allows for up to 60 requests per hour. Unauthenticated requests are associated with the originating IP address, and not the user making requests. +### Requests from GitHub Apps -{% data reusables.enterprise.rate_limit %} +Requests from a GitHub App may be either user-to-server or server-to-server requests. For more information about rate limits for GitHub Apps, see "[Rate limits for GitHub Apps](/developers/apps/building-github-apps/rate-limits-for-github-apps)." + +### Requests from GitHub Actions + +You can use the built-in `GITHUB_TOKEN` to authenticate requests in GitHub Actions workflows. For more information, see "[Automatic token authentication](/actions/security-guides/automatic-token-authentication)." + +When using `GITHUB_TOKEN`, the rate limit is 1,000 requests per hour per repository.{% ifversion fpt or ghec %} For requests to resources that belong to an enterprise account on {% data variables.product.product_location %}, {% data variables.product.prodname_ghe_cloud %}'s rate limit applies, and the limit is 15,000 requests per hour per repository.{% endif %} -Note that [the Search API has custom rate limit rules](/rest/reference/search#rate-limit). +### Checking your rate limit status + +The Rate Limit API and a response's HTTP headers are authoritative sources for the current number of API calls available to you or your app at any given time. + +#### Rate Limit API + +You can use the Rate Limit API to check your rate limit status without incurring a hit to the current limit. For more information, see "[Rate limit](/rest/reference/rate-limit)." + +#### Rate limit HTTP headers The returned HTTP headers of any API request show your current rate limit status: @@ -411,11 +444,9 @@ If you exceed the rate limit, an error response returns: > } ``` -You can [check your rate limit status](/rest/reference/rate-limit) without incurring an API hit. - -### Increasing the unauthenticated rate limit for OAuth applications +### Increasing the unauthenticated rate limit for OAuth Apps -If your OAuth application needs to make unauthenticated calls with a higher rate limit, you can pass your app's client ID and secret before the endpoint route. +If your OAuth App needs to make unauthenticated calls with a higher rate limit, you can pass your app's client ID and secret before the endpoint route. ```shell $ curl -u my_client_id:my_client_secret {% data variables.product.api_url_pre %}/user/repos diff --git a/content/rest/reference/rate-limit.md b/content/rest/reference/rate-limit.md index eca80ace69b2..2d659cc122d0 100644 --- a/content/rest/reference/rate-limit.md +++ b/content/rest/reference/rate-limit.md @@ -31,6 +31,6 @@ objects: * The `integration_manifest` object provides your rate limit status for the [GitHub App Manifest code conversion](/apps/building-github-apps/creating-github-apps-from-a-manifest/#3-you-exchange-the-temporary-code-to-retrieve-the-app-configuration) endpoint. -For more information on the headers and values in the rate limit response, see "[Rate limiting](/rest#rate-limiting)." +For more information on the headers and values in the rate limit response, see "[Resources in the REST API](/rest/overview/resources-in-the-rest-api#rate-limit-http-headers)." {% include rest_operations_at_current_path %} diff --git a/content/rest/reference/search.md b/content/rest/reference/search.md index 19f0a12d4587..eabd6296180d 100644 --- a/content/rest/reference/search.md +++ b/content/rest/reference/search.md @@ -23,14 +23,14 @@ Unless another sort option is provided as a query parameter, results are sorted ### Rate limit +{% data reusables.enterprise.rate_limit %} + The Search API has a custom rate limit. For requests using [Basic Authentication](/rest#authentication), [OAuth](/rest#authentication), or [client ID and secret](/rest#increasing-the-unauthenticated-rate-limit-for-oauth-applications), you can make up to 30 requests per minute. For unauthenticated requests, the rate limit allows you to make up to 10 requests per minute. -{% data reusables.enterprise.rate_limit %} - See the [rate limit documentation](/rest/reference/rate-limit) for details on determining your current rate limit status. diff --git a/data/reusables/apps/api-rate-limits-non-ghec.md b/data/reusables/apps/api-rate-limits-non-ghec.md deleted file mode 100644 index 3cb153d11f00..000000000000 --- a/data/reusables/apps/api-rate-limits-non-ghec.md +++ /dev/null @@ -1 +0,0 @@ -{% data variables.product.prodname_github_apps %} making server-to-server requests use the installation's minimum rate limit of 5,000 requests per hour. Organization installations with more than 20 users receive another 50 requests per hour for each user. Installations that have more than 20 repositories receive another 50 requests per hour for each repository. The maximum rate limit for an installation is 12,500 requests per hour. diff --git a/data/reusables/apps/user-to-server-rate-limits-ghec.md b/data/reusables/apps/user-to-server-rate-limits-ghec.md new file mode 100644 index 000000000000..1d6190588eb2 --- /dev/null +++ b/data/reusables/apps/user-to-server-rate-limits-ghec.md @@ -0,0 +1,4 @@ +User-to-server requests are subject to a higher limit of 15,000 requests per hour and per authenticated user in the following scenarios. + +- The request is from a {% data variables.product.prodname_github_app %} that's owned by a {% data variables.product.prodname_ghe_cloud %} organization. +- The request is from an {% data variables.product.prodname_oauth_app %} that's owned or approved by a {% data variables.product.prodname_ghe_cloud %} organization. diff --git a/data/reusables/apps/user-to-server-rate-limits.md b/data/reusables/apps/user-to-server-rate-limits.md new file mode 100644 index 000000000000..81551fa1d4e2 --- /dev/null +++ b/data/reusables/apps/user-to-server-rate-limits.md @@ -0,0 +1 @@ +{% ifversion ghes %}By default, user-to-server{% else %}User-to-server{% endif %} requests are limited to {% ifversion ghae %}15,000{% elsif fpt or ghec or ghes %}5,000{% endif %} requests per hour and per authenticated user. All requests from OAuth applications authorized by a user or a personal access token owned by the user, and requests authenticated with any of the user's authentication credentials, share the same quota of {% ifversion ghae %}15,000{% elsif fpt or ghec or ghes %}5,000{% endif %} requests per hour for that user. \ No newline at end of file diff --git a/data/reusables/enterprise/rate_limit.md b/data/reusables/enterprise/rate_limit.md index 74a3372af27e..a79474a3b362 100644 --- a/data/reusables/enterprise/rate_limit.md +++ b/data/reusables/enterprise/rate_limit.md @@ -1,3 +1,9 @@ -{% ifversion ghes or ghae %} -Note that the limits mentioned above are the default rate limits for {% data variables.product.product_name %}. Contact your site administrator to confirm if rate limits are enabled and how they are configured. +{% ifversion ghes %} + +{% note %} + +**Note**: The following rate limits are the default rate limits for {% data variables.product.product_name %}. Contact your site administrator to confirm the rate limits for {% data variables.product.product_location %}. + +{% endnote %} + {% endif %} diff --git a/data/reusables/rest-api/always-check-your-limit.md b/data/reusables/rest-api/always-check-your-limit.md new file mode 100644 index 000000000000..f16b1bcb0b27 --- /dev/null +++ b/data/reusables/rest-api/always-check-your-limit.md @@ -0,0 +1,5 @@ +{% note %} + +**Note**: You can confirm your current rate limit status at any time. For more information, see "[Checking your rate limit status](/rest/overview/resources-in-the-rest-api#checking-your-rate-limit-status)." + +{% endnote %} diff --git a/data/reusables/shortdesc/rate_limits_github_apps.md b/data/reusables/shortdesc/rate_limits_github_apps.md index bcba4f706af6..8bbd3534fd71 100644 --- a/data/reusables/shortdesc/rate_limits_github_apps.md +++ b/data/reusables/shortdesc/rate_limits_github_apps.md @@ -1 +1 @@ -Rate limits for GitHub Apps help control the rate of traffic. +Rate limits for {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} help control the rate of traffic to {% data variables.product.product_location %}.