diff --git a/website/.vitepress/config.mts b/website/.vitepress/config.mts
index 65746dbaba..40a538a7db 100644
--- a/website/.vitepress/config.mts
+++ b/website/.vitepress/config.mts
@@ -107,7 +107,8 @@ export default defineConfig({
{ text: 'Electric', link: '/product/electric' },
{ text: 'Cloud', link: '/product/cloud', items: [
{ text: 'Sign-up', link: '/product/cloud/sign-up' },
- { text: 'Onboarding', link: '/product/cloud/onboarding' }
+ { text: 'Onboarding', link: '/product/cloud/onboarding' },
+ { text: 'Usage', link: '/product/cloud/usage' }
]
},
{ text: 'PGlite', link: '/product/pglite' },
diff --git a/website/product/cloud/usage.md b/website/product/cloud/usage.md
new file mode 100644
index 0000000000..79713c6961
--- /dev/null
+++ b/website/product/cloud/usage.md
@@ -0,0 +1,101 @@
+---
+title: Usage
+description: >-
+ Usage instructions for the Electric Cloud private BETA.
+outline: [2, 3]
+---
+
+
+
+
+
+# Usage
+
+Usage instructions for the Electric Cloud .
+
+> [!Warning] Invitation only
+> These instructions are only for teams that have been invited to the Electric Cloud private BETA. To get access, please [sign-up](./sign-up) to the waitlist.
+
+## Using the Electric Cloud
+
+Once onboarded, you will be given a source ID and secret for each Postgres database you've connected to Electric:
+
+
+
+
+
+You should store these somewhere secure (like in your password manager) and use them when making requests to the cloud API at `https://api.electric-sql.cloud/v1/shape`.
+
+### Curl example
+
+For example using `curl`:
+
+```shell
+export SOURCE_ID="8ea4e5fb-9217-4ca6-80b7-0a97581c4c10"
+export SOURCE_SECRET=""
+
+export SHAPE_DEFINITION="table=items&offset=-1"
+
+curl -i "https://api.electric-sql.cloud/v1/shape?$SHAPE_DEFINITION\
+ &source_id=$SOURCE_ID\
+ &source_secret=$SOURCE_SECRET"
+```
+
+## Security model
+
+The source ID is a key that uniquely identifies your Postgres database.
+
+The source secret is a token that grants access to it. You should treat the source secret as securely as you would your database password.
+
+> [!Warning] Do not leak your source secret to the client
+> If you use the source secret from an insecure client, then this exposes it to malicious users, who can then use it to connect to your cloud API.
+
+### Proxy auth
+
+The recommended pattern for secure use of the Electric Cloud is to add the source ID and secret parameter to the origin request made by your [auth proxy](/docs/guides/auth) or API. (You can proxy requests to Electric using an edge worker, or an API. In many cases, this can be your [existing backend API](/blog/2024/11/21/local-first-with-your-existing-api#using-your-existing-api)).
+
+See the [security guide](/docs/guides/security) for more context.
+
+#### Example
+
+In your client, request the shape as normal, without the `source_id` and `source_secret` parameters. For example here using the [Typescript client](/docs/api/clients/typescript):
+
+```ts
+import { ShapeStream } from '@electric-sql/client'
+
+const stream = new ShapeStream({
+ url: `https://your-api-or-proxy.example.com/v1/shape`,
+ params: {
+ table: `items`
+ }
+})
+```
+
+Then add the source ID and secret to the origin request in your [auth proxy](/docs/guides/auth). For example here using a Next.js [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)):
+
+```ts
+export async function GET(req: Request) {
+ const proxyUrl = new URL(req.url)
+
+ // ... validate and authorize the request ...
+
+ // Construct the origin URL.
+ const originUrl = new URL(`/v1/shape`, `https://api.electric-sql.cloud`)
+ proxyUrl.searchParams.forEach((value, key) => {
+ originUrl.searchParams.set(key, value)
+ })
+
+ // Add the source params.
+ originUrl.searchParams.set(`source_id`, process.env.SOURCE_ID)
+ originUrl.searchParams.set(`source_secret`, process.env.SOURCE_SECRET)
+
+ // Proxy the authorised request on to the Electric Cloud.
+ return fetch(originUrl, {headers: req.headers})
+}
+```
+
+### Support
+
+Let us know if you have any questions. We'll be very happy to help.
diff --git a/website/static/img/docs/cloud/access-creds.png b/website/static/img/docs/cloud/access-creds.png
new file mode 100644
index 0000000000..1b9c344891
Binary files /dev/null and b/website/static/img/docs/cloud/access-creds.png differ