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