feat: tighter/more explicit security recommendations for self-hosting

docs/deployment/self-host-supertokens.mdx

@@ -30,6 +30,7 @@
 To deploy the Core Service you must configure two things: the actual API and the database.
 - The core service can be deployed using a **Docker** image or directly inside your VM.
 - The supported database is **PostgreSQL**. The minimum required version is `13.0`.
+- The core service is a **trusted backend component**. Deploy it on a private network reachable only by your backend, and never expose it directly to the public internet or to your frontend. When it must be reachable more widely, protect it with an [API key](/docs/platform-configuration/supertokens-core/api-keys). See [Secure the core](#secure-the-core) for details.
 
 :::info
 **SuperTokens Core** has dropped **MySQL** and **MongoDB** support with the `11.0.0` release.
@@ -216,9 +217,12 @@
 </BackendTabs.TabItem>
 </BackendTabs>
 
-:::info Security
-No API key exists by default.
-Check [the API keys documentation](/docs/platform-configuration/supertokens-core/api-keys) to see how to add one.
+:::caution Security
+The SuperTokens Core is a backend service, meant to be accessed only by your own backend through the backend SDKs. It must **not** be exposed directly to the public internet, to your frontend, or to end users. Any caller that can reach the Core can perform administrative operations on your users' data.
+
+- **No API key exists by default.** Whenever the Core is reachable by anything other than your backend, protect it with an [API key](/docs/platform-configuration/supertokens-core/api-keys).
+- **Prefer network isolation.** Deploy the Core on a private network (for example a VPC or an internal subnet) reachable only by your backend.
+- **Add further controls as needed:** restrict access by [IP address](/docs/platform-configuration/supertokens-core/ip-allow-deny) and serve traffic over [TLS/SSL](/docs/platform-configuration/supertokens-core/add-ssl-via-nginx).
 :::
 
 ### 4. Set up the database
@@ -961,6 +965,17 @@
 
 ```
 
+## Secure the core
+
+The SuperTokens Core exposes administrative operations over its API — creating and updating users, issuing password-reset and passwordless codes, managing tenants, and more. By design these are available to the connecting backend, because the Core has no direct channel to your frontend and relies on your backend to mediate every request and to deliver codes and tokens to end users.
+
+This trust model means the Core must be treated like your database: reachable only by your own backend, never by untrusted clients.
+
+- **Isolate the network.** Run the Core on a private network or subnet that only your backend can reach. This is the primary protection and applies regardless of any other setting.
+- **Set an API key.** If the Core can be reached by anything beyond your backend, configure an [API key](/docs/platform-configuration/supertokens-core/api-keys). Note that within a single deployment all callers share the same key; an API key is therefore not a substitute for network isolation between tenants.
+- **Restrict by IP and use TLS.** Optionally limit access by [IP address](/docs/platform-configuration/supertokens-core/ip-allow-deny) and terminate [TLS/SSL](/docs/platform-configuration/supertokens-core/add-ssl-via-nginx) in front of the Core.
+- **Enforce tenant scoping in your backend.** Sessions and other objects carry their tenant as a signed claim. When an action is restricted to a specific tenant, verify the tenant in your backend rather than relying on the URL the request arrived on.
+
 ## References
 
 ### Docker compose file

docs/platform-configuration/supertokens-core/api-keys.mdx

@@ -19,6 +19,10 @@ The backend SDK uses API keys to authenticate requests to the SuperTokens core.
 
 By default, there is no API key required. If you add an API key to the core's configuration or use the managed service, you need to add it to your backend SDK code. Otherwise, the core throws a `401` error.
 
+:::caution
+Running without an API key is only safe when the Core is on a private network reachable exclusively by your backend. If the Core can be reached from anywhere else, configure an API key — and ideally also restrict access by [IP address](/docs/platform-configuration/supertokens-core/ip-allow-deny) and serve traffic over [TLS/SSL](/docs/platform-configuration/supertokens-core/add-ssl-via-nginx). Any caller that can reach the Core can perform administrative operations on your users' data. See [Secure the core](/docs/deployment/self-host-supertokens#secure-the-core).
+:::
+
 ## Before you start
 
 :::caution no-title

docs/quickstart/introduction.mdx

@@ -71,6 +71,7 @@ You can check the following diagram for a high level overview of how the service
 
 - You can also host the **SuperTokens Core** yourself. In that case your backend will communicate with a service that exists inside your infrastructure.
 - If you are using a backend for which we do not have an SDK, you will have to spin up an additional auth service in a language for which we do have a backend SDK (NodeJS, Python or Golang).
+- The **SuperTokens Core** is a trusted backend component. It should only be reachable by your backend, never exposed directly to the public internet or your frontend. When self-hosting, see [Secure the core](/docs/deployment/self-host-supertokens#secure-the-core).
   :::
 
 ### Recipes