From dac2ff0aaa7c91940a2775976e8901709ab0ea13 Mon Sep 17 00:00:00 2001
From: Hieu <phamhieu1998@gmail.com>
Date: Wed, 4 Feb 2026 16:25:32 +0700
Subject: [PATCH] feat: display FGA permission groups with OR logic (#42438)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Update API reference docs to properly render FGA permission groups,
showing the OR relationship between permission sets.

## What is the current behavior?

Right now, only the first FGA permission group is shown, missing
alternative permission sets that also grant access to an endpoint.

## What is the new behavior?

Display all FGA permission groups with "or" separator between them.

<img width="542" height="165" alt="Screenshot 2026-02-04 at 1 16 23 PM"
src="https://github.com/user-attachments/assets/adee529d-e15d-4912-98c4-1c5a8cd4c9d7"
/>



<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

**Documentation**
- Improved the API reference documentation by reorganizing how endpoint
permissions are displayed. Permissions are now grouped with clear "or"
separators between groups, making it easier to understand the complete
set of permission requirements for each API endpoint.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../docs/features/docs/Reference.sections.tsx | 57 +++++++++++--------
 1 file changed, 33 insertions(+), 24 deletions(-)

diff --git a/apps/docs/features/docs/Reference.sections.tsx b/apps/docs/features/docs/Reference.sections.tsx
index a3f17c83513..c71510e1032 100644
--- a/apps/docs/features/docs/Reference.sections.tsx
+++ b/apps/docs/features/docs/Reference.sections.tsx
@@ -1,20 +1,5 @@
-import { isFeatureEnabled } from 'common'
-import { Fragment } from 'react'
-import ReactMarkdown from 'react-markdown'
-import {
-  Badge,
-  TabsContent_Shadcn_,
-  TabsList_Shadcn_,
-  TabsTrigger_Shadcn_,
-  Tabs_Shadcn_,
-  cn,
-} from 'ui'
-
-import { type IApiEndPoint } from './Reference.api.utils'
-import { RefInternalLink } from './Reference.navigation.client'
-import { ApiOperationBodySchemeSelector } from './Reference.ui.client'
 import ApiSchema from '~/components/ApiSchema'
-import { REFERENCES, clientSdkIds } from '~/content/navigation.references'
+import { clientSdkIds, REFERENCES } from '~/content/navigation.references'
 import {
   getApiEndpointById,
   getCliSpec,
@@ -23,7 +8,7 @@ import {
   getSelfHostedApiEndpointById,
   getTypeSpec,
 } from '~/features/docs/Reference.generated.singleton'
-import { MDXRemoteRefs, getRefMarkdown } from '~/features/docs/Reference.mdx'
+import { getRefMarkdown, MDXRemoteRefs } from '~/features/docs/Reference.mdx'
 import type { MethodTypes } from '~/features/docs/Reference.typeSpec'
 import { formatMethodSignature } from '~/features/docs/Reference.typeSpec'
 import {
@@ -38,6 +23,21 @@ import {
 import type { AbbrevApiReferenceSection } from '~/features/docs/Reference.utils'
 import { normalizeMarkdown } from '~/features/docs/Reference.utils'
 import { CodeBlock } from '~/features/ui/CodeBlock/CodeBlock'
+import { isFeatureEnabled } from 'common'
+import { Fragment } from 'react'
+import ReactMarkdown from 'react-markdown'
+import {
+  Badge,
+  cn,
+  Tabs_Shadcn_,
+  TabsContent_Shadcn_,
+  TabsList_Shadcn_,
+  TabsTrigger_Shadcn_,
+} from 'ui'
+
+import { type IApiEndPoint } from './Reference.api.utils'
+import { RefInternalLink } from './Reference.navigation.client'
+import { ApiOperationBodySchemeSelector } from './Reference.ui.client'
 
 type RefSectionsProps = {
   libraryId: string
@@ -286,8 +286,10 @@ async function ApiEndpointSection({ link, section, servicePath }: ApiEndpointSec
     : await getApiEndpointById(section.id)
   if (!endpointDetails) return null
 
-  const endpointFgaPermissions =
-    endpointDetails.security?.find((sec) => 'fga_permissions' in sec)?.fga_permissions ?? []
+  const endpointFgaPermissionGroups =
+    endpointDetails.security
+      ?.filter((sec) => 'fga_permissions' in sec)
+      .map((sec) => sec.fga_permissions) ?? []
   const pathParameters = (endpointDetails.parameters ?? []).filter((param) => param.in === 'path')
   const queryParameters = (endpointDetails.parameters ?? []).filter((param) => param.in === 'query')
   const bodyParameters =
@@ -360,16 +362,23 @@ async function ApiEndpointSection({ link, section, servicePath }: ApiEndpointSec
             </ul>
           </section>
         )}
-        {endpointFgaPermissions.length > 0 && (
+        {endpointFgaPermissionGroups.length > 0 && (
           <section>
             <h3 className="mb-3 text-base text-foreground">
               The fine-grained token must include the following permissions to access this endpoint:
             </h3>
             <ul>
-              {endpointFgaPermissions.map((perm) => (
-                <li key={perm} className="list-['-'] ml-2 pl-2">
-                  <span className="font-mono text-sm font-medium text-foreground">{perm}</span>
-                </li>
+              {endpointFgaPermissionGroups.map((group, groupIndex) => (
+                <Fragment key={groupIndex}>
+                  {groupIndex > 0 && (
+                    <li className="my-2 text-foreground-lighter text-sm italic">or</li>
+                  )}
+                  {group.map((perm, permIndex) => (
+                    <li key={permIndex} className="list-['-'] ml-2 pl-2">
+                      <span className="font-mono text-sm font-medium text-foreground">{perm}</span>
+                    </li>
+                  ))}
+                </Fragment>
               ))}
             </ul>
           </section>