API consents platform use case (#3688)

mooreds · web-flow · commit 295d77c0457c · 2025-05-06T12:28:14.000-06:00
diff --git a/astro/public/img/docs/get-started/use-cases/api-consents-consent-screen.png b/astro/public/img/docs/get-started/use-cases/api-consents-consent-screen.png
diff --git a/astro/public/img/docs/get-started/use-cases/api-consents-scopes.png b/astro/public/img/docs/get-started/use-cases/api-consents-scopes.png
diff --git a/astro/public/img/docs/get-started/use-cases/github-authorized-applications.png b/astro/public/img/docs/get-started/use-cases/github-authorized-applications.png
diff --git a/astro/src/content/docs/extend/examples/api-gateways/index.mdx b/astro/src/content/docs/extend/examples/api-gateways/index.mdx
@@ -6,6 +6,7 @@ section: extend
 subcategory: examples
 tertcategory: api gateways
 navOrder: 0
+tags: api consents
 ---
 import ApiGatewayArchitectureDiagram from 'src/diagrams/docs/extend/examples/api-gateways/_example-api-gateway-architecture.astro';
 import InlineField from 'src/components/InlineField.astro';
@@ -67,7 +68,7 @@ Here are some example API gateway integrations.
 
 * [Amazon API Gateway](/docs/extend/examples/api-gateways/aws-api-gateway)
 * [HAProxy](/docs/extend/examples/api-gateways/haproxy-api-gateway)
-* <a href="https://hasura.io/learn/graphql/hasura-authentication/integrations/fusion-auth/">Hasura</a> (external documentation)
+* [Hasura](https://hasura.io/learn/graphql/hasura-authentication/integrations/fusion-auth/) (external documentation)
 * [Kong Gateway](/docs/extend/examples/api-gateways/kong-gateway)
 * [ngrok Cloud Edge](/docs/extend/examples/api-gateways/ngrok-cloud-edge)
 
diff --git a/astro/src/content/docs/get-started/use-cases/_api-consents-platform-description.mdx b/astro/src/content/docs/get-started/use-cases/_api-consents-platform-description.mdx
@@ -1,3 +1,3 @@
-If you have APIs that others are building on top of, use FusionAuth to manage user data, and want to allow your users to delegate access to their data accessible via your APIs, FusionAuth can handle the full OAuth grant, including custom scopes and customization of access tokens.
+If you have APIs that others are building on top of, use FusionAuth to manage user data, and want to allow your users to delegate access to their data accessible via your APIs, FusionAuth can handle the OAuth grant, including custom scopes and access token customization. The application or AI agent can then use the token to access APIs on your user's behalf.
 
-In this case, FusionAuth is part of your API strategy, handling user consents and access token generation.
+FusionAuth can be part of your API platform strategy, handling user consent and access token generation.
diff --git a/astro/src/content/docs/get-started/use-cases/api-consents-platform.mdx b/astro/src/content/docs/get-started/use-cases/api-consents-platform.mdx
diff --git a/astro/src/content/docs/get-started/use-cases/authorization-hub.mdx b/astro/src/content/docs/get-started/use-cases/authorization-hub.mdx
@@ -4,6 +4,7 @@ description: Integrate with third party platforms, using FusionAuth to safely st
 section: get started
 subcategory: use cases
 navOrder: 100
+tags: api consents
 ---
 import Aside from 'src/components/Aside.astro';
 import StoreRefreshTokensDiagram from 'src/diagrams/docs/get-started/use-cases/authorization-hub/store-refresh-token.astro';
@@ -30,6 +31,8 @@ With the authorization hub implementation, you can manage tokens for social prov
 * Microsoft Entra Id
 * Any provider supporting OIDC
 
+This is the inverse of the API consents use case](/docs/get-started/use-cases/api-consents-platform).
+
 ## Solution
 
 Use FusionAuth as your hub for this functionality. FusionAuth can be a centralized repository for long lived tokens and make it easier to integrate with third party platforms.
@@ -133,7 +136,8 @@ In each of these cases there's a third party platform API which is used to provi
 
 ## Additional Documentation
 
-* [The Third-Party Service Authorization Mode](/docs/lifecycle/authenticate-users/oauth/modes#third-party-service-authorization)
+* [The third-party service authorization mode](/docs/lifecycle/authenticate-users/oauth/modes#third-party-service-authorization)
+* [The API consents use case](/docs/get-started/use-cases/api-consents-platform)
 * [List of supported social identity providers](/docs/lifecycle/authenticate-users/identity-providers/#social-identity-providers)
 * [List of SDKs](/docs/sdks)
 * [Identity link APIs](/docs/apis/identity-providers/links)
diff --git a/astro/src/content/docs/get-started/use-cases/index.mdx b/astro/src/content/docs/get-started/use-cases/index.mdx
@@ -41,7 +41,7 @@ Here's a table of the common use cases. If you have questions, feel free to [con
 | Use standards based authentication for my APIs or other software systems. | [Machine to machine communication (m2m)](/docs/get-started/use-cases/machine-to-machine) | <M2MCommunicationDescription /> |
 | Embed FusionAuth in my deployable application to provide a single interface for my engineering team, while allowing my customers to bring their own identity providers. | [Identity broker](/docs/get-started/use-cases/identity-broker) | <IdentityBrokerDescription /> |
 | Easily add 'authorize' buttons for third party platforms, and manage the tokens used to access third party APIs. | [Authorization hub](/docs/get-started/use-cases/authorization-hub) | <AuthorizationHubDescription /> |
-| Build a platform for others to access my APIs on behalf of my users using OAuth grants. | API user consents and delegated access | <APIConsentsPlatformDescription /> |
+| Build a platform for others to access my APIs on behalf of my users using OAuth grants. | [API user consents and delegated access](/docs/get-started/use-cases/api-consents-platform) | <APIConsentsPlatformDescription /> |
 | Control all the UX and use FusionAuth only for the backend of my auth system. | Data store | <DataStoreDescription /> |
 
 
diff --git a/astro/src/content/docs/lifecycle/authenticate-users/oauth/endpoints.mdx b/astro/src/content/docs/lifecycle/authenticate-users/oauth/endpoints.mdx
@@ -5,6 +5,7 @@ navcategory: login-methods
 section: lifecycle
 subcategory: authenticate users
 tertcategory: oauth
+tags: api consents
 ---
 import Aside from 'src/components/Aside.astro';
 import API from 'src/components/api/API.astro';
diff --git a/astro/src/content/docs/lifecycle/authenticate-users/oauth/modes.mdx b/astro/src/content/docs/lifecycle/authenticate-users/oauth/modes.mdx
@@ -5,7 +5,7 @@ navcategory: login-methods
 section: lifecycle
 subcategory: authenticate users
 tertcategory: oauth
-tags: authorization hub
+tags: authorization hub, api consents
 ---
 import Aside from 'src/components/Aside.astro';
 import Breadcrumb from 'src/components/Breadcrumb.astro';
diff --git a/astro/src/content/docs/lifecycle/authenticate-users/oauth/scopes.mdx b/astro/src/content/docs/lifecycle/authenticate-users/oauth/scopes.mdx
@@ -5,6 +5,7 @@ navcategory: login-methods
 section: lifecycle
 subcategory: authenticate users
 tertcategory: oauth
+tags: api consents
 ---
 import AdvancedPlanBlurb from 'src/content/docs/_shared/_advanced-plan-blurb.astro';
 import ApplicationScopesSettings from 'src/content/docs/_shared/_application-scopes-settings.mdx';
diff --git a/astro/src/content/docs/sdks/index.mdx b/astro/src/content/docs/sdks/index.mdx
@@ -3,7 +3,7 @@ title: Client Libraries and SDKs Overview
 description: An overview of FusionAuth Client Libraries and SDKs.
 navcategory: developer
 section: sdks
-tags: authorization hub
+tags: authorization hub, api consents
 ---
 import HowToUseClientLibraries from 'src/content/docs/sdks/_how-to-use-client-libraries.mdx';
 import SdkUpgradePolicy from 'src/content/docs/sdks/_upgrade-policy.mdx';
diff --git a/astro/src/content/json/exampleapps.json b/astro/src/content/json/exampleapps.json
@@ -623,6 +623,12 @@
     "description": "An express/JavaScript application used for a walkthrough of a FusionAuth setup",
     "language": "javascript"
   },
+  {
+    "url": "https://github.com/fusionauth/fusionauth-example-api-consents-platform",
+    "name": "API Consents Platform",
+    "description": "Example repo for a third-party application platform with scopes and consent management.",
+    "language": "javascript"
+  },
   {
     "url": "https://github.com/FusionAuth/fusionauth-example-mock-testing-vs-dev-server",
     "name": "Why Mocking Sucks - FusionAuth",
diff --git a/astro/src/diagrams/docs/get-started/use-cases/api-consents/application-api-request.astro b/astro/src/diagrams/docs/get-started/use-cases/api-consents/application-api-request.astro
@@ -0,0 +1,30 @@
+---
+import Diagram from "src/components/mermaid/SequenceDiagram.astro";
+const { alt } = Astro.props;
+
+//language=Mermaid
+const diagram = `
+sequenceDiagram
+    participant App as MoneyScope
+    participant APIs as Changebank APIs
+    participant FusionAuth
+  
+
+    App ->> App : Query All Users To Update Data
+    loop for each user
+       App ->> APIs : Requests Data Using User's (Expired) Access Token
+       APIs ->> APIs : Validates Access Token
+       APIs ->> App : Returns Unauthorized
+       App ->> App : Retrieve User's Refresh Token
+       App ->> FusionAuth : Request New Access Token Using Refresh Token
+       FusionAuth ->> FusionAuth : Validates Refresh Token
+       FusionAuth ->> App : Sends New Access Token
+       App ->> APIs : Requests Data Using New Access Token
+       APIs ->> APIs : Validates Access Token
+       APIs ->> App : Returns Data
+       App ->> App : Stores Data
+    end 
+
+`;
+---
+<Diagram code={diagram} alt={alt} />
diff --git a/astro/src/diagrams/docs/get-started/use-cases/api-consents/user-authorize.astro b/astro/src/diagrams/docs/get-started/use-cases/api-consents/user-authorize.astro
@@ -0,0 +1,28 @@
+---
+import Diagram from "src/components/mermaid/SequenceDiagram.astro";
+const { alt } = Astro.props;
+
+//language=Mermaid
+const diagram = `
+sequenceDiagram
+    participant User as Logged In User/Browser
+    participant App as MoneyScope
+    participant FusionAuth
+
+    User ->> App : Requests Login Page
+    App ->> User : Redirects To FusionAuth Authorize URL
+    User ->> FusionAuth : Requests Login Page
+    FusionAuth ->> User : Returns Login Page
+    User ->> FusionAuth : Authenticates 
+    FusionAuth ->> FusionAuth : Validates Credentials
+    FusionAuth ->> User : Displays Consent Page
+    User ->> FusionAuth : Accepts Consents
+    FusionAuth ->> User : Returns Redirect To Application
+    User ->> App : Requests Redirect URL
+    App ->> FusionAuth : Requests Tokens, Including Refresh Token
+    FusionAuth ->> App : Sends Tokens
+    App ->> App : Stores Tokens
+    App ->> User : Display Page
+`;
+---
+<Diagram code={diagram} alt={alt} />
