feat(DOCS-5540): add My Account components docs for Web

main/config/navigation/universal-components.json

@@ -26,6 +26,14 @@
                 "docs/get-started/universal-components/web/components/sso-provider-create",
                 "docs/get-started/universal-components/web/components/sso-provider-edit"
               ]
+            },
+            {
+              "group": "My Account",
+              "pages": [
+                "docs/get-started/universal-components/web/components/my-account-overview",
+                "docs/get-started/universal-components/web/components/user-mfa-management",
+                "docs/get-started/universal-components/web/components/user-passkey-management"
+              ]
             }
           ]
         }

main/docs/get-started/universal-components/web/components/my-account-overview.mdx

@@ -0,0 +1,367 @@
+---
+title: Build a Self-Service Account Security Interface with My Account API
+description: Learn how to configure Universal Components to build self-service account security interfaces with My Account API.
+sidebarTitle: Build Account Security UI
+---
+
+import { ReleaseStageNotice } from "/snippets/ReleaseStageNotice.jsx";
+
+<ReleaseStageNotice
+    feature="Auth0 Universal Components"
+    stage="beta"
+    terms="true"
+    contact="Auth0 Support"
+/>
+
+My Account components allow you to embed a self-service authentication management interface directly into your web application. Your users can enroll and remove multi-factor authentication (MFA) factors and manage passkeys within your web application.
+
+## How it works
+
+My Account components use the My Account API's [authentication methods](/docs/manage-users/my-account-api#manage-authentication-methods) endpoints to render an authentication-management UI inside your application. 
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+The [My Account API](/docs/manage-users/my-account-api) currently enforces low [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations), especially on free-tier tenants. This may cause errors while using these components.
+</Callout>
+
+When an authenticated user opens their account settings screen, the Auth0 SDK retrieves an [access token](/docs/secure/tokens/access-tokens) scoped to the My Account API audience.
+
+The components use this token to call the My Account API [`/me/v1/authentication-methods`](/docs/api/myaccount/authentication-methods/get-authentication-methods) as the logged-in user, so each user can only view and modify their own authentication methods.
+
+### Available components
+
+| **Component** | **API endpoint** |
+| :--- | :--- |
+| [**UserMFAMgmt**](/docs/get-started/universal-components/web/components/user-mfa-management) Enroll and delete MFA factors: email OTP, SMS OTP, TOTP (authenticator application), push notifications, passkeys, and recovery codes. | `/me/v1/authentication-methods` |
+| [**UserPasskeyMgmt**](/docs/get-started/universal-components/web/components/user-passkey-management) Register and revoke WebAuthn passkeys. | `/me/v1/authentication-methods` (type: passkey) |
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+* These components create **end-user self-service** interfaces. End users can enroll, list, and remove every authentication method on their own account: email OTP, SMS OTP, TOTP (authenticator application), push notifications, passkeys, and recovery codes.
+* For **delegated admin** interfaces in which a user manages an Auth0 [Organization](/docs/manage-users/organizations), read [Build a Delegated Admin Interface](/docs/get-started/universal-components/web/components/build-delegated-admin).
+</Callout>
+
+
+<Tabs>
+<Tab title="React (SPA)">
+
+## Prerequisites
+
+### Enable My Account API
+
+1. Navigate to [**Dashboard > Applications > APIs**](https://manage.auth0.com/#/apis).
+2. Select **Activate My Account API** to enable it for your tenant.
+
+### Create the application and configure My Account API permissions
+
+1. Navigate to [**Dashboard > Applications > Applications**](https://manage.auth0.com/#/applications), and select **Create Application**.
+2. Select **Single Page Web Applications**.
+3. Select the **Settings** tab and add your **Callback, Logout, and Web Origins URLs**. For example: `http://localhost:5173`.
+4. Select the **API Access** tab.
+5. Select **Edit** for the **Auth0 My Account API** to add the **User-delegated Access** permissions:
+
+    `create:me:authentication_methods`
+    `read:me:authentication_methods`
+    `update:me:authentication_methods`
+    `delete:me:authentication_methods`
+    `read:me:factors`
+
+6. Select **Save** to save the permissions.
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+* The user’s access token only includes permissions that were granted during login.
+* Request all five scopes to allow users to enroll, review, and remove authentication methods.
+</Callout>
+
+### Set up the database and test user
+
+1. Navigate to [**Dashboard > Authentication > Database**](https://manage.auth0.com/#/connections/database) to create a database connection.
+2. In the **Applications** tab of the database, enable your application.
+3. Navigate to [**Dashboard > User Management > Users**](https://manage.auth0.com/#/users).
+4. Select **Create User** to create a user assigned to the new database connection.
+5. Select **Create** to add the new user; use this new user for testing.
+
+## Configure your application 
+
+### Install the component
+
+<CodeGroup>
+```bash pnpm wrap lines
+pnpm add @auth0/universal-components-react
+```
+
+```bash npm wrap lines
+npm install @auth0/universal-components-react
+```
+</CodeGroup>
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+The install command also adds the `@auth0/universal-components-core` dependency for shared utilities and Auth0 integration.
+</Callout>
+
+### Configure environment variables
+
+Create a `.env` file in your project root:
+
+```bash wrap lines
+VITE_AUTH0_DOMAIN=YOUR_TENANT_DOMAIN.auth0.com
+VITE_AUTH0_CLIENT_ID=YOUR_SPA_CLIENT_ID
+```
+
+### Configure Universal Components
+
+Import `Auth0Provider` and `Auth0ComponentProvider` and set `interactiveErrorHandler="popup"` so that MFA enrollment and deletion challenges are handled in a popup rather than redirecting away from the page.
+
+```tsx App.tsx wrap lines
+import { Auth0Provider } from "@auth0/auth0-react";
+import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
+
+const domain = import.meta.env.VITE_AUTH0_DOMAIN;
+const clientId = import.meta.env.VITE_AUTH0_CLIENT_ID;
+
+export default function App() {
+  return (
+    <Auth0Provider
+      domain={domain}
+      clientId={clientId}
+      authorizationParams={{ redirect_uri: window.location.origin }}
+      interactiveErrorHandler="popup"
+    >
+      <Auth0ComponentProvider domain={domain}>
+        {/* your application */}
+      </Auth0ComponentProvider>
+    </Auth0Provider>
+  );
+}
+```
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+* Users must be authenticated before the My Account components are rendered. 
+* Components automatically load the logged-in user's authentication methods from the My Account API.
+</Callout>
+
+<Warning>
+You are responsible for ensuring that your use of the My Account API and Universal Components complies with your security policies and applicable laws, including any permissions granted to your end users.
+</Warning>
+
+</Tab>
+
+<Tab title="Next.js (RWA)">
+
+## Prerequisites
+
+### Enable My Account API
+
+1. Navigate to [**Dashboard > Applications > APIs**](https://manage.auth0.com/#/apis).
+2. Select **Activate My Account API** to enable it for your tenant.
+
+### Create the application and configure My Account API permissions
+
+1. Navigate to [**Dashboard > Applications > Applications**](https://manage.auth0.com/#/applications), and select **Create Application**.
+2. Select **Regular Web Application**.
+3. Select the **Settings** tab and add your **Allowed Callback, and Allowed Logout URLs**. For example: `http://localhost:3000`.
+4. Select the **API Access** tab.
+5. Select **Edit** for the **Auth0 My Account API** to add the **User-delegated Access** permissions:
+
+    `create:me:authentication_methods`
+    `read:me:authentication_methods`
+    `update:me:authentication_methods`
+    `delete:me:authentication_methods`
+    `read:me:factors`
+
+6. Select **Save** to save the permissions.
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+* The user’s access token only includes permissions that were granted during login.
+* Request all five scopes to allow users to enroll, review, and remove authentication methods.
+</Callout>
+
+### Set up the database and test user
+
+1. Navigate to [**Dashboard > Authentication > Database**](https://manage.auth0.com/#/connections/database) to create a database connection.
+2. In the **Applications** tab of the database, enable your application.
+3. Navigate to [**Dashboard > User Management > Users**](https://manage.auth0.com/#/users).
+4. Select **Create User** to create a user assigned to the new database connection.
+5. Select **Create** to add the new user; use this new user for testing.
+
+## Configure your application
+
+### Install the component
+
+<CodeGroup>
+```bash pnpm wrap lines
+pnpm add @auth0/universal-components-react
+```
+
+```bash npm wrap lines
+npm install @auth0/universal-components-react
+```
+</CodeGroup>
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+The install command also adds the `@auth0/universal-components-core` dependency for shared utilities and Auth0 integration.
+</Callout>
+
+### Configure environment variables
+
+Create a `.env.local` file in your Next.js project root:
+
+```js wrap lines
+NEXT_PUBLIC_AUTH0_DOMAIN=YOUR_TENANT_DOMAIN.auth0.com
+NEXT_PUBLIC_AUTH0_CLIENT_ID=YOUR_RWA_CLIENT_ID
+AUTH0_SECRET=YOUR_AUTH0_SECRET
+AUTH0_ISSUER_BASE_URL="https://YOUR_TENANT_DOMAIN.auth0.com"
+```
+
+For complete Next.js SDK setup, read the [Auth0 Next.js SDK documentation](/docs/quickstart/webapp/nextjs).
+
+### Configure Universal Components
+
+Add `Auth0ComponentProvider` from the `/rwa` subpath to your root layout and set `interactiveErrorHandler="popup"` so that MFA enrollment and deletion challenges are handled in a popup rather than redirecting away from the page.
+
+```tsx app/layout.tsx wrap lines
+import { Auth0ComponentProvider } from "@auth0/universal-components-react/rwa";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Auth0ComponentProvider
+          domain={process.env.NEXT_PUBLIC_AUTH0_DOMAIN!}
+          interactiveErrorHandler="popup"
+        >
+          {children}
+        </Auth0ComponentProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+* Users must be authenticated before the My Account components are rendered. 
+* Components automatically load the logged-in user's authentication methods from the My Account API.
+</Callout>
+
+<Warning>
+You are responsible for ensuring that your use of the My Account API and Universal Components complies with your security policies and applicable laws, including any permissions granted to your end users.
+</Warning>
+
+</Tab>
+
+<Tab title="shadcn">
+
+## Prerequisites
+
+### Enable My Account API
+
+1. Navigate to [**Dashboard > Applications > APIs**](https://manage.auth0.com/#/apis).
+2. Select **Activate My Account API** to enable it for your tenant.
+
+### Create the application and configure My Account API permissions
+
+1. Navigate to [**Dashboard > Applications > Applications**](https://manage.auth0.com/#/applications), and select **Create Application**.
+2. Select **Single Page Web Applications**.
+3. Select the **Settings** tab and add your **Callback, Logout, and Web Origins URLs**. For example: `http://localhost:5173`.
+4. Select the **API Access** tab.
+5. Select **Edit** for the **Auth0 My Account API** to add the **User-delegated Access** permissions:
+
+    `create:me:authentication_methods`
+    `read:me:authentication_methods`
+    `update:me:authentication_methods`
+    `delete:me:authentication_methods`
+    `read:me:factors`
+
+6. Select **Save** to save the permissions.
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+* The user’s access token only includes permissions that were granted during login.
+* Request all five scopes to allow users to enroll, review, and remove authentication methods.
+</Callout>
+
+### Set up the database and test user
+
+1. Navigate to [**Dashboard > Authentication > Database**](https://manage.auth0.com/#/connections/database) to create a database connection.
+2. In the **Applications** tab of the database, enable your application.
+3. Navigate to [**Dashboard > User Management > Users**](https://manage.auth0.com/#/users).
+4. Select **Create User** to create a user assigned to the new database connection.
+5. Select **Create** to add the new user; use this new user for testing.
+
+## Configure your application
+
+### Install the component
+
+Run the shadcn CLI to add the components directly to your project source:
+
+```bash MFA management wrap lines
+npx shadcn@latest add https://auth0-universal-components.vercel.app/r/my-account/user-mfa-management.json
+```
+
+```bash Passkey management wrap lines
+npx shadcn@latest add https://auth0-universal-components.vercel.app/r/my-account/user-passkey-management.json
+```
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+The install command adds the component source into `src/components/auth0/my-account/` along with all UI dependencies and the `@auth0/universal-components-core` dependency for shared utilities and Auth0 integration.
+</Callout>
+
+
+### Configure environment variables
+
+Create a `.env.local` file in your project root:
+
+```js wrap lines
+VITE_AUTH0_DOMAIN=YOUR_TENANT.auth0.com
+VITE_AUTH0_CLIENT_ID=YOUR_SPA_CLIENT_ID
+```
+
+### Configure Universal Components
+
+Import `Auth0Provider` and `Auth0ComponentProvider` and set `interactiveErrorHandler="popup"` so that MFA enrollment and deletion challenges are handled in a popup rather than redirecting away from the page.
+
+
+```tsx App.tsx wrap lines
+import { Auth0Provider } from "@auth0/auth0-react";
+import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
+
+const domain = import.meta.env.VITE_AUTH0_DOMAIN;
+const clientId = import.meta.env.VITE_AUTH0_CLIENT_ID;
+
+export default function App() {
+  return (
+    <Auth0Provider
+      domain={domain}
+      clientId={clientId}
+      authorizationParams={{ redirect_uri: window.location.origin }}
+      interactiveErrorHandler="popup"
+    >
+      <Auth0ComponentProvider domain={domain}>
+        {/* your application */}
+      </Auth0ComponentProvider>
+    </Auth0Provider>
+  );
+}
+```
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+* Users must be authenticated before the My Account components are rendered. 
+* Components automatically load the logged-in user's authentication methods from the My Account API.
+</Callout>
+
+<Warning>
+You are responsible for ensuring that your use of the My Account API and Universal Components complies with your security policies and applicable laws, including any permissions granted to your end users.
+</Warning>
+
+</Tab>
+</Tabs>
+
+## Learn more
+
+<CardGroup cols={2}>
+  <Card title="Configure UserMFAMgmt" icon="gear" href="/docs/get-started/universal-components/web/components/user-mfa-management">
+    MFA factors reference: props, customization, TypeScript definitions, and advanced subcomponents.
+  </Card>
+
+  <Card title="Configure UserPasskeyMgmt" icon="gear" href="/docs/get-started/universal-components/web/components/user-passkey-management">
+    Passkey management reference: hooks, message overrides, and CSS class targets.
+  </Card>
+
+</CardGroup>