docs: Document secure and insecure modes (#2405)

Docs update for #2404

I think we should also extend other parts of the documentation to
explain that this secret must be passed when making shape requests.
Otherwise, people will follow the docs but it won't work. So either the
docs show usage in INSECURE mode which doesn't seem ideal, or we add the
secret where needed. But i'm a bit afraid of polluting code
snippets/docs with a secret. Open for suggestions on the best way to
communicate this in the docs.

Author: kevin-dp

website/docs/api/config.md

@@ -105,6 +105,34 @@ Suffix for the logical replication publication and slot name.
 
 ## Electric
 
+### ELECTRIC_SECRET
+
+<EnvVarConfig
+    name="ELECTRIC_SECRET"
+    required={true}
+    example="1U6ItbhoQb4kGUU5wXBLbxvNf">
+
+Secret for shape requests to the [HTTP API](/docs/api/http). This is required unless `ELECTRIC_INSECURE` is set to `true`.
+By default, the Electric API is public and authorises all shape requests against this secret.
+More details are available in the [security guide](/docs/guides/security).
+
+</EnvVarConfig>
+
+### ELECTRIC_INSECURE
+
+<EnvVarConfig
+    name="ELECTRIC_INSECURE"
+    defaultValue="false"
+    example="true">
+
+When set to `true`, runs Electric in insecure mode and does not require an `ELECTRIC_SECRET`.
+Use with caution.
+API requests are unprotected and may risk exposing your database.
+Good for development environments.
+If used in production, make sure to [lock down access](/docs/guides/security#network-security) to Electric.
+
+</EnvVarConfig>
+
 ### ELECTRIC_INSTANCE_ID
 
 <EnvVarConfig
@@ -135,7 +163,7 @@ Name of the electric service. Used as a resource identifier and namespace.
     example="true">
 
 Expose some unsafe operations that faciliate integration testing.
-Do not enable this production.
+Do not enable this in production.
 
 </EnvVarConfig>
 

website/docs/guides/security.md

@@ -35,7 +35,7 @@ Electric is a [sync service](/product/electric) that runs in front of Postgres.
   </a>
 </figure>
 
-This API is [public by default](#public-by-default). It should be secured in production using [network security](#network-security) and/or an [authorization proxy](#authorization).
+This API is [public by default](#public-by-default). It should be secured in production using an [API token](#api-token), [network security](#network-security) and/or an [authorization proxy](#authorization).
 
 ### Public by default
 
@@ -62,6 +62,12 @@ Electric is designed to run behind an [authorizing proxy](/docs/guides/auth#requ
 
 This is the primary method for securing data access to clients and apps and is documented in detail, with examples, in the [Auth guide](/docs/guides/auth).
 
+### API token
+
+Access to Electric can be secured with an [API token](/docs/api/config#electric-secret). This is a secret string that can be set when starting Electric and will be used to authenticate requests to the Electric HTTP API. When an API token is set, Electric will require all requests to include the API token. 
+
+The token should *not* be sent from the client as it will be exposed in the HTTP requests. Instead, it should be added by the [authorizing proxy](/docs/guides/auth#requests-can-be-proxied) when proxying requests to Electric.
+
 ## Encryption
 
 Electric syncs ciphertext as well as it syncs plaintext. You can encrypt and decrypt data in HTTP middleware or in the local client.

website/public/docker-compose.yaml

@@ -23,6 +23,9 @@ services:
     image: electricsql/electric
     environment:
       DATABASE_URL: postgresql://postgres:password@postgres:5432/electric?sslmode=disable
+      # Not suitable for production. Only use insecure mode in development or if you've otherwise secured the Electric API.
+      # See https://electric-sql.com/docs/guides/security
+      ELECTRIC_INSECURE: true
     ports:
       - "3000:3000"
     depends_on: