The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
Add partner integration guide and mermaid diagrams (#45730)
Matt Linkous71e94a159045
diff --git a/apps/docs/components/Mermaid.tsx b/apps/docs/components/Mermaid.tsxnew file mode 100644index 00000000000..1ffbf346c4c--- /dev/null+++ b/apps/docs/components/Mermaid.tsx@@ -0,0 +1,25 @@+import { renderMermaidSVG } from 'beautiful-mermaid'++interface MermaidProps {+ chart: string+}++export function Mermaid({ chart }: MermaidProps) {+ const svg = renderMermaidSVG(chart, {+ bg: 'hsl(var(--background-default))',+ fg: 'hsl(var(--foreground-default))',+ accent: 'hsl(var(--brand-default))',+ muted: 'hsl(var(--foreground-light))',+ line: 'hsl(var(--border-strong))',+ border: 'hsl(var(--border-strong))',+ surface: 'hsl(var(--background-surface-200))',+ transparent: true,+ })++ return (+ <div+ className="my-6 overflow-x-auto rounded-md border bg-surface-100 p-4 [&>svg]:mx-auto [&>svg]:h-auto [&>svg]:max-w-full"+ dangerouslySetInnerHTML={{ __html: svg }}+ />+ )+}diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsindex 26cfdc1186c..82204bdb456 100644--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts@@ -3101,6 +3101,10 @@ export const integrations: NavMenuConstant = {name: 'Supabase for Platforms',url: '/guides/integrations/supabase-for-platforms',},+ {+ name: 'Supabase partner integration guide',+ url: '/guides/integrations/partner-integration-guide',+ },],},{ name: 'Integrations', url: undefined, items: [] },diff --git a/apps/docs/content/guides/integrations/partner-integration-guide.mdx b/apps/docs/content/guides/integrations/partner-integration-guide.mdxnew file mode 100644index 00000000000..44cc2915556--- /dev/null+++ b/apps/docs/content/guides/integrations/partner-integration-guide.mdx@@ -0,0 +1,278 @@+---+id: 'partner-integration-guide'+title: 'Supabase Partner Integration Guide'+subtitle: 'Integrate Supabase with your platform or product.'+description: 'This guide explains how a Supabase partner can integrate with the Supabase platform via OAuth.'+---++This guide assumes you have already followed [the Build a Supabase Integration guide](/docs/guides/integrations/build-a-supabase-oauth-integration) and have a working OAuth client.++When a Supabase user clicks the **Install Integration** button in the Dashboard, they are redirected to your system to begin the OAuth flow. You can implement this redirect in one of two ways:++- **[Simple redirect](#method-1-simple-redirect)**: Easier to build, but your system cannot verify that the incoming user was sent by Supabase.+- **[Signed redirect](#method-2-signed-redirect)**: More work to build, but cryptographically verifies that the redirect originated from Supabase. **Recommended for production integrations.**++Pick the method that fits your security requirements, then follow the matching section below.++## Method 1: Simple redirect++In this method, you implement a single `GET` endpoint. Supabase redirects the user to this endpoint when they click **Install Integration**, and your endpoint kicks off the OAuth flow.++<Mermaid+ chart={`sequenceDiagram+ autonumber+ participant User+ participant Browser+ participant Partner as Partner (OAuth Client)+ participant Supabase as Supabase (OAuth Authorization Server/Protected Resource)++ Note over Browser: Supabase Dashboard Open++ User->>Browser: Clicks "Install Integration"++ Browser->>Partner: "Connect to Partner" Click Handler Page+ Partner->>Browser: Redirect to Supabase Authorization Page++ Browser->>Supabase: Request Authorization+ Supabase->>Browser: Redirect to Consent Screen++ Browser->>User: Display Consent Screen+ User->>Browser: Gives Consent++ Browser->>Supabase: Submit User Consent+ Supabase->>Browser: Redirect to Partner With Authorization Code++ Browser->>Partner: Submit Authorization Code++ Partner->>Supabase: Exchange Authorization Code for Token+ Supabase->>Partner: Return Token++ Partner->>Supabase: Request Management API Resources+ Supabase->>Partner: Return Resources++ Partner->>Browser: Ok 200, OAuth Flow Complete++ Browser->>User: Display "Integration Installed" Message`}++/>++### Step 1: Implement the redirect endpoint++Expose a `GET` endpoint at any URL you control:++```+GET https://<your-host>/<optional-path>?project_id=<supabase-project_ref>&organization_slug=<supabase-org-slug>+```++Supabase will append the following query parameters to the URL when redirecting:++| Param | Description |+| ------------------- | ---------------------------------------------------------------------------------------------- |+| `project_id` | Supabase project ref of the project where the user clicked the **Install Integration** button. |+| `organization_slug` | Supabase organization slug where the user clicked the **Install Integration** button. |++Save these parameters in your system. You can use them to fetch project or organization details, or to pre-select a project or organization in your UI once the OAuth flow is complete.++Your endpoint may ask the user to sign up, sign in, or perform other setup tasks on your website. Once those are complete, immediately [redirect to the Supabase authorization URL](/docs/guides/integrations/build-a-supabase-oauth-integration#redirecting-to-the-authorize-url) without further user interaction. This starts the OAuth flow.++### Step 2: Share your endpoint with Supabase++Send Supabase the URL of your endpoint so we can configure the **Install Integration** button to redirect there.++## Method 2: Signed redirect++In this method, Supabase signs a JWT before redirecting the user. You verify the signature, generate a one-time redirect record, and return its URL to Supabase. Supabase then redirects the user to that URL. This guarantees that any redirect your system handles originated from Supabase.++You will implement two endpoints:++1. A `POST` endpoint that validates the signed JWT and returns a unique redirect URL.+2. A `GET` endpoint that handles the user once they are redirected to that URL.++<Mermaid+ chart={`sequenceDiagram+ autonumber+ participant User+ participant Browser+ participant Partner as Partner (OAuth Client)+ participant Supabase as Supabase (OAuth Authorization Server/Protected Resource)++ Note over Browser: Supabase Dashboard Open++ User->>Browser: Clicks "Install Integration"++ Browser->>Supabase: Request Redirect URL Generation+ Supabase->>Partner: Send Signed JWT+ Partner->>Partner: Validate JWT+ Partner->>Partner: Generate Unique Redirect URL+ Partner->>Supabase: Return Redirect URL+ Supabase->>Browser: Redirect to the Redirect URL++ Browser->>Partner: Visit Redirect URL+ Partner->>Partner: Validate Redirect Record+ Partner->>Browser: Optional User Actions+ Browser->>User: User Performs Optional Actions+ User->>Browser: User Optional Actions Complete+ Browser->>Partner: User Optional Actions Complete+ Partner->>Browser: Redirect to Supabase Authorization Page++ Browser->>Supabase: Request Authorization+ Supabase->>Browser: Redirect to Consent Screen++ Browser->>User: Display Consent Screen+ User->>Browser: Gives Consent++ Browser->>Supabase: Submit User Consent+ Supabase->>Browser: Redirect to Partner With Authorization Code++ Browser->>Partner: Submit Authorization Code++ Partner->>Supabase: Exchange Authorization Code for Token+ Supabase->>Partner: Return Token++ Partner->>Supabase: Request Management API Resources+ Supabase->>Partner: Return Resources++ Partner->>Browser: Ok 200, OAuth Flow Complete++ Browser->>User: Display "Integration Installed" Message`}++/>++### Step 1: Exchange public keys with Supabase++Supabase generates two key-pairs, one for staging, one for production, and shares the public keys with you. Save both public keys and their key IDs in your system. The keys are PEM-encoded EC P-256.++Example:++```+===============Staging==================++Key ID: pik_3038669348a3ea75dbaf0655+Public Key:+-----BEGIN PUBLIC KEY-----+MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEnj3NmwrLPPH/3isvpS601ndQP9Mk+zqppdLDV9YfmoF4wavTyb9UTVE5pJ0fukpo5aOoNb4fBZgESsedIUoEn8Q==+-----END PUBLIC KEY-----++==============Production================++Key ID: pik_89e80ddbca9df41b97e28986+Public Key:+-----BEGIN PUBLIC KEY-----+MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWCGhwtFWn4jpWZNeyZpTlaAdq/tD+/yBaN0gFPpS8LTFiCPFgnWKbVe3RfExXh7bEhcrEUdWycmYvwrNklWWHRA==+-----END PUBLIC KEY-----+```++Look up the correct public key by the `kid` field in the JWT header.++Storing keys by ID enables zero-downtime key rotation. When Supabase rotates keys, we share new key-pairs and start signing JWTs with the new key ID. Your system picks the correct key based on `kid` without any code changes.++<Admonition type="note">++In future, we plan to publish keys at a `.../.well-known/jwks.json` URL and fully automate key rotation. For now this is done manually.++</Admonition>++### Step 2: Implement the redirect record endpoint++This endpoint receives the signed JWT from Supabase and returns a one-time redirect URL.++Host the endpoint at any URL and path you control. Do not require authentication on this endpoint, but apply rate limiting to prevent abuse.++```+POST https://<your-api-host>/<your-api-path>+Content-Type: application/json+```++#### Request body++```json+{+ "token": "<signed-jwt>"+}+```++#### JWT fields++The token is a JWT signed with the ES256 private key.++**Protected header (JOSE header)**++| Field | Required | Description |+| ----- | -------- | ---------------------------------------------------------------------------------------------------------- |+| `alg` | Yes | Always `ES256` — the only signing algorithm currently supported. |+| `kid` | Yes | The key ID identifying the key pair. Use this to pick the correct public key when verifying the signature. |++**Payload (claims)**++| Claim | Required | Description |+| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |+| `iss` | Yes | Always `supabase`. |+| `aud` | Yes | A unique string identifying the audience of this JWT. Usually a URL. |+| `iat` | Yes | Issued-at timestamp (seconds since epoch). |+| `exp` | Yes | Expiry timestamp — at most 5 minutes after `iat`. |+| `organization_slug` | No | The Supabase organization the user is connecting from. Use to pre-select the org during the OAuth consent screen. |+| `project_id` | No | The Supabase project ref the user wants to connect. Use to pre-select a Supabase project in your UI. |++**Signature**++The header and claims are signed with the EC P-256 private key.++#### Validation++When you receive a request:++1. Read the `kid` field from the JWT header and look up the matching public key.+2. Verify the JWT signature with that public key.+3. Verify that `alg` is `ES256`.+4. Verify that `iss` is `supabase`.+5. Verify that `aud` matches the value you agreed with Supabase.+6. Verify that the current time is between `iat` and `exp`.++If any check fails, return `401 Unauthorized`.++If validation succeeds, generate a UUID to identify this redirect record (also called an integration record), save it in your system with an expiry (typically 1 hour), and return it in the response. The expiry prevents records from accumulating and limits the window in which a leaked record can be used.++#### Response body++```json+{+ "integrationId": "<a unique uuid>",+ "redirectUrl": "https://<your-api-host>/<your-api-path>/<integration-id>",+ "expiresAt": "<timestamp>"+}+```++| Field | Description |+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |+| `integrationId` | A UUID uniquely identifying the redirect record. |+| `redirectUrl` | The URL the user will be redirected to. Must contain the `integrationId` somewhere in its path so you can retrieve the record on redirect. |+| `expiresAt` | The time when the redirect record expires (typically 1 hour from creation). The user must begin the flow before this time. |++### Step 3: Implement the redirect handler endpoint++This is the `GET` endpoint at the `redirectUrl` you returned in the previous step. The redirect record's UUID must be in its path.++When a user arrives at this endpoint:++1. Extract the redirect record UUID from the URL path.+2. Look it up in your system. If it doesn't exist or has expired, return `401 Unauthorized`.+3. Optionally, walk the user through any setup required on your side — for example, signing up, signing in, or configuring your system so the integration will work.+4. Redirect the user to the [Supabase authorization URL](/docs/guides/integrations/build-a-supabase-oauth-integration#redirecting-to-the-authorize-url) to start the OAuth flow.++<Admonition type="tip">++If you need the user to perform setup steps on your site, design the experience as a wizard that ends by redirecting to the Supabase authorization URL. This minimizes the chance of users getting distracted, navigating elsewhere on your site, and abandoning the OAuth flow.++</Admonition>++### Step 4: Share your details with Supabase++Send Supabase the following so we can configure the **Install Integration** button:++- The URL of your redirect record endpoint ([Step 2](#step-2-implement-the-redirect-record-endpoint)).+- The URL pattern of your redirect handler endpoint ([Step 3](#step-3-implement-the-redirect-handler-endpoint)).+- The `aud` claim value you want Supabase to send in the signed JWT.++Ask Supabase for the public keys and key IDs for the staging and production environments.diff --git a/apps/docs/features/docs/MdxBase.shared.tsx b/apps/docs/features/docs/MdxBase.shared.tsxindex 264292b1928..6e6ccca207f 100644--- a/apps/docs/features/docs/MdxBase.shared.tsx+++ b/apps/docs/features/docs/MdxBase.shared.tsx@@ -9,6 +9,7 @@ import { ComputeDiskLimitsTable } from '~/components/ComputeDiskLimitsTable'import { Extensions } from '~/components/Extensions'import Image, { type ImageProps } from '~/components/Image'import { JwtGeneratorSimple } from '~/components/JwtGenerator'+import { Mermaid } from '~/components/Mermaid'import { MetricsStackCards } from '~/components/MetricsStackCards'import { NavData } from '~/components/NavData'import { Price } from '~/components/Price'@@ -70,6 +71,7 @@ const components = {JwtGeneratorSimple,Link,McpConfigPanel,+ Mermaid,MetricsStackCards,NamedCodeBlock,NavData,diff --git a/apps/docs/package.json b/apps/docs/package.jsonindex 78f80fcb0e4..558762f3f23 100644--- a/apps/docs/package.json+++ b/apps/docs/package.json@@ -60,6 +60,7 @@"acorn": "^8.11.3","acorn-typescript": "^1.4.13","ai-commands": "workspace:*",+ "beautiful-mermaid": "^1.1.3","common": "workspace:*","common-tags": "^1.8.2","config": "workspace:*",diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 3704a536c41..0bfbabe208b 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -368,6 +368,9 @@ importers:ai-commands:specifier: workspace:*version: link:../../packages/ai-commands+ beautiful-mermaid:+ specifier: ^1.1.3+ version: 1.1.3common:specifier: workspace:*version: link:../../packages/common@@ -9311,6 +9314,9 @@ packages:resolution: {integrity: sha512-NF+epuEdnUYVlGuhaxbbq+dvJttwLnGY+YixlXlME5KpQ5W3CnXA5cVTneY3SPbPDRkcjMbifrwmFYcClgOZeg==}engines: {node: '>= 0.8'}+ resolution: {integrity: sha512-TItrtrAyHp1vwFfFVYauWGrquouk/6SS21Aq3RsxindSYZODcN4xYrPZD6BiZRU+o5mKJzDPz9MUSMvELdylyg==}+resolution: {integrity: sha512-Nik3Sc0ncrMK4UUdXQmAnRtzmNQTAAXmXIopizwZ1W1t8QmfJj+zL4OA2I7XPTPW5z5TDqv4hRo/JzouDJnX3A==}@@ -10594,6 +10600,9 @@ packages:resolution: {integrity: sha512-kOrWphBi8TOZyiJZqsgqIle0lw+tzmnQK83pV9dZUd01Nm2POECSyFQMAuarzZdYqQW7FH9RaYOuaRo3h+bQ3w==}+ resolution: {integrity: sha512-zxxR9k+rx5ktMwT/FwyLdPCrq7xN6e4VGGHH8hA01vVYKjTFik7nHOxBnAYtrgYUB1RpAiLvA1/U2YraWxyKKg==}+resolution: {integrity: sha512-QpLs9D9v9kArv4lfDEgg1X/gN5XLnf/A6l9cs8SPZLRZR3ZkY9+kwIQTxm+fsSej5UMYGE8fdoaZVIBlqG0XTw==}@@ -25802,6 +25811,11 @@ snapshots:dependencies:safe-buffer: 5.1.2+ dependencies:+ elkjs: 0.11.1+ entities: 7.0.1+@@ -27197,6 +27211,8 @@ snapshots:+ [email protected]: {}+