github · docs-bot · Jul 30, 2025 · Jul 29, 2025 · Jul 29, 2025 · Jul 30, 2025
diff --git a/...hub-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md b/...hub-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md
@@ -30,29 +30,33 @@ If you do hit a rate limit and need to retry an API request, use the `x-ratelimi
 
 ## Secure your app's credentials
 
-You can generate a private key and client secret for your {% data variables.product.prodname_github_app %}. With these credentials, your app can generate installation access tokens, user access tokens, and refresh tokens. These tokens can be used to make API requests on behalf of an app installation or user.
+You can generate a private key and client secret for your {% data variables.product.prodname_github_app %}. Private keys are used to generate installation access tokens, while client secrets are used to get user access tokens and refresh tokens. These tokens can be used to make API requests on behalf of an app installation or user.
 
-You must store these credentials securely. The storage mechanism depends on your integrations architecture and the platform that it runs on. In general, you should use a storage mechanism that is intended to store sensitive data on the platform that you are using.
+You must store private keys, tokens, and client secrets securely. However, the storage mechanism and its relative security depends on your integrations architecture and the platform that it runs on. In general, you should use a storage mechanism that is intended to store sensitive data on the platform that you are using.
 
 ### Private keys
 
-The private key for your {% data variables.product.prodname_github_app %} grants access to every account that the app is installed on.
+The private key for your {% data variables.product.prodname_github_app %} grants access to every account that the app is installed on. It **must** be stored securely and never shared broadly.
 
 Consider storing your {% data variables.product.prodname_github_app %}'s private key in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/en-gb/products/key-vault), and making it sign-only.
 
 Alternatively, you can store the key as an environment variable. However, this is not as strong as storing the key in a key vault. If an attacker gains access to the environment, they can read the private key and gain persistent authentication as the {% data variables.product.prodname_github_app %}.
 
-You should never hard code your private key in your app, even if your code is stored in a private repository. If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you should never ship your private key with your app.
+You should never hard code your private key in your app, even if your code is stored in a private repository. If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you must never ship your private key with your app.
 
-You should not generate more private keys than you need. You should delete private keys that you no longer need. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps).
+You should not generate more private keys than you need. You should delete private keys that are no longer in use. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps).
 
 ### Client secrets
 
-Client secrets are used to generate user access tokens for your app, unless your app uses device flow. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-device-flow-to-generate-a-user-access-token).
+Client secrets are required to generate user access tokens for your app, unless your app uses the device flow. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-device-flow-to-generate-a-user-access-token).
 
-If your app is a website or web app, consider storing your client secret in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault), or as an encrypted environment variable or secret on your server.
+If your app is a confidential client, meaning it can safely keep the client secret secure, consider storing your client secret in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault), or as an encrypted environment variable or secret on your server.
 
-If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you cannot secure your client secret. You should use caution if you plan to gate access to your own services based on tokens generated by your app because anyone can access the client secret to generate a token.
+If your app is a public client (a native app that runs on the user's device, CLI utility, or single-page web application), you cannot secure your client secret. You will have to ship the client secret in the application's code, and you should use PKCE to better secure the authentication flow. You should use caution if you plan to gate access to your own services based on tokens generated by your app because public clients are trivially spoofable - anyone can reuse your app's client ID to sign in.
+
+#### Don't enable device flow without reason
+
+It is preferable to use the authorization code with PKCE over the device flow, if you are concerned about using the client secret in a public client. The device flow does not require redirect URIs at all, which means that an attacker can use the device flow to remotely impersonate your app as part of a phishing attack. For this reason, do not enable the device flow for your application unless you are using the app in a constrained environment (CLIs, IoT devices, or headless systems).
 
 ### Installation access tokens, user access tokens, and refresh tokens
 

diff --git a/...apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app.md b/...apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app.md
@@ -50,13 +50,19 @@ To find the list of organizations a user is a member of, you can use the "List o
 
 With a client secret, your app can authorize a user and generate user access tokens. These tokens can be used to make API requests on behalf of a user.
 
-You must store your app's client secret and any generated tokens securely. The storage mechanism depends on your integrations architecture and the platform that it runs on. In general, you should use a storage mechanism that is intended to store sensitive data on the platform that you are using.
+You must store your app's client secret and any generated tokens securely. The storage mechanism and its relative security depends on your integrations architecture and the platform that it runs on. In general, you should use a storage mechanism that is intended to store sensitive data on the platform that you are using.
 
 ### Client secrets
 
-If your app is a website or web app, consider storing your client secret in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault), or as an encrypted environment variable or secret on your server.
+Client secrets are required to generate user access tokens for your app, unless your app uses the device flow. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow).
 
-If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you cannot secure your client secret. You should use caution if you plan to gate access to your own services based on tokens generated by your app, because anyone can access the client secret to generate a token.
+If your app is a confidential client, meaning it can safely keep the client secret secure, consider storing your client secret in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault), or as an encrypted environment variable or secret on your server.
+
+If your app is a public client (a native app that runs on the user's device, CLI utility, or single-page web application), you cannot secure your client secret. You will have to ship the client secret in the application's code, and you should use PKCE to better secure the authentication flow. You should use caution if you plan to gate access to your own services based on tokens generated by your app because public clients are trivially spoofable - anyone can reuse your app's client ID to sign in.
+
+#### Don't enable device flow without reason
+
+It is preferable to use the authorization code with PKCE over the device flow, if you are concerned about using the client secret in a public client. The device flow does not require redirect URIs at all, which means that an attacker can use the device flow to remotely impersonate your app as part of a phishing attack. For this reason, do not enable the device flow for your application unless you are using the app in a constrained environment (CLIs, IoT devices, or headless systems).
 
 ### User access tokens
 

diff --git a/...curity-settings-for-your-organization/audit-log-events-for-your-organization.md b/...curity-settings-for-your-organization/audit-log-events-for-your-organization.md
@@ -12,10 +12,8 @@ shortTitle: Audit log events
 autogenerated: audit-logs
 ---
 
-> [!NOTE]
-{% ifversion ghes %}
-> * This article contains the events available in the latest version of {% data variables.product.prodname_ghe_server %}. Some of the events may not be available in previous versions.
-{% endif %}
+> [!NOTE]{% ifversion ghes %}
+> * This article contains the events available in the latest version of {% data variables.product.prodname_ghe_server %}. Some of the events may not be available in previous versions.{% endif %}
 > * This article contains the events that may appear in your organization's audit log. For the events that can appear in a user account's security log{% ifversion ghec or ghes %} or the audit log for an enterprise{% endif %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events){% ifversion ghec or ghes %} and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise).{% else %}.{% endif %}
 > * {% data reusables.webhooks.webhooks-as-audit-log-alternative %}