zuplo 7.8.7 → 7.8.9

package/docs/getting-started/dev-portal/portal.mdx

@@ -0,0 +1,146 @@
+---
+category: Developer Portal
+showLastModified: false
+suggestEdit: false
+sidebar_label: Portal
+title: Getting Started with Developer Portal - Portal
+description:
+  Publish a developer portal in the Zuplo Portal, customize API documentation,
+  assign a consumer key, and test an authenticated request.
+---
+
+<WizardSteps build="dev-portal" method="portal" />
+
+<MethodTabs build="dev-portal" method="portal" />
+
+Publish API documentation and let developers manage their assigned API keys.
+You'll create a Todo API, customize its developer portal, and make an
+authenticated request from the portal's playground.
+
+## Prerequisites
+
+- A [Zuplo account](https://portal.zuplo.com).
+- An email address you can use to sign in to the developer portal.
+
+## Build and test your developer portal
+
+<Stepper>
+
+1. **Create a project and sample API**
+
+   Open [**Projects**](https://portal.zuplo.com/+/account/projects), click **New
+   Project**, and select **API & MCP Gateway**. Name it `my-dev-portal` and
+   click **Create Project**.
+
+   In **Code → config/routes.oas.json**, select **Start with Example API**, then
+   **Complete Import**. The Route Designer now lists the Todo API routes. Your
+   project also includes a `docs` directory for the developer portal.
+
+2. **Customize the portal**
+
+   In the **Code** file tree, open `docs/zudoku.config.tsx`. Set `site.title`
+   and `metadata.title` to `Todo Developer Portal`, and set
+   `metadata.description` to `Explore the Todo API and manage your API keys.`
+   Keep the other settings, including `apis`, `authentication`, and `apiKeys`.
+
+   The `apis` configuration reads `../config/routes.oas.json` and displays it at
+   `/api`. Editing your routes updates the API reference.
+
+   Open `docs/pages/introduction.mdx` and replace its contents with:
+
+   ```mdx title="docs/pages/introduction.mdx"
+   ---
+   title: Welcome to the Todo API
+   description: Sign in, find your API key, and make your first request.
+   ---
+
+   Use the Todo API to retrieve tasks for your application.
+
+   1. Sign in using the email address registered as a key manager.
+   2. Open **API Keys** from your profile menu to find your assigned key.
+   3. Open **API Reference** and try **List todos** with that key.
+   ```
+
+   Save the changes. The introduction already has a navigation entry. See
+   [Writing content](../../dev-portal/zudoku/writing.mdx) for more options.
+
+3. **Protect the sample route**
+
+   Open `config/routes.oas.json` in the **Route Designer** and select **List
+   todos** (`GET /todos`). Open **Policies → Add Policy**, search for **API Key
+   Authentication**, and accept its default configuration.
+
+   <ModalScreenshot>
+
+   ![Choose the API Key Authentication policy](/media/step-3-add-api-key-auth/choose-policy.png)
+
+   </ModalScreenshot>
+
+   Keep this policy first in the inbound policy chain. On the same route, open
+   **Deny All Origins (CORS)** and select **Allow All Origins** so the developer
+   portal can call it from the browser. Save your changes.
+
+   In the code view, add `info.description` to the OpenAPI file and set it to
+   `GET /todos requires a bearer API key.` Save again.
+
+   Click **Test** next to the route's path and send a request without a key.
+   Expect `401 Unauthorized`. This step protects `GET /todos`; apply
+   authentication to other routes before using them for private data.
+
+4. **Assign a key to a developer**
+
+   Open
+   [**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services).
+   Select **Dev** and click **Create Consumer**. Set **Subject** to
+   `tutorial-consumer`, enter your email under **Key managers**, and leave
+   **Metadata** as `{}`. Click **Save consumer**.
+
+   <ModalScreenshot>
+
+   ![Create an API consumer and assign its key manager](/media/api-key-consumer-bucket-portal-ui/create-consumer-modal.png)
+
+   </ModalScreenshot>
+
+   A key manager can manage the consumer's keys after signing in. Signing in
+   doesn't create a consumer automatically. See
+   [API key management](../../articles/api-key-management.mdx).
+
+5. **Open and test the developer portal**
+
+   Open **Deployment URLs** and copy the **Dev Portal** URL for your working
+   copy. Open it in a new tab. Visit `/introduction` to check your new page.
+
+   Sign in using the same email address you entered under **Key managers**. The
+   template includes a demo sign-in provider for this tutorial. Open **API
+   Keys** from your profile menu and confirm your consumer's key appears.
+
+   Open **API Reference → List todos → Test**. Expand **Authentication**, select
+   `tutorial-consumer`, and click **Send**. Expect `200 OK` and todos in the
+   response. Select **None** under Authentication and send again: expect
+   `401 Unauthorized`.
+
+   If the key isn't listed, check the key manager email and that the consumer is
+   in the **Dev** bucket. If the browser reports a CORS error, check that this
+   route allows requests from the portal.
+
+6. **Deploy for other developers**
+
+   Follow [Deploy to the edge](../gateway/deploy-to-the-edge/index.mdx) to
+   connect your Git repository and deploy. Open **Deployment URLs** for the
+   production deployment and copy its **Dev Portal** URL.
+
+   Create a consumer in the **Prod** API key bucket and repeat the signed-in
+   request there. Dev and Production keys are separate.
+
+   Before inviting users, replace the demo login with your own
+   [authentication provider](../../dev-portal/zudoku/configuration/authentication.md)
+   and configure [CORS](../../articles/cors.mdx) to allow your portal's origin.
+
+</Stepper>
+
+## Next steps
+
+- [Customize the theme](../../dev-portal/zudoku/customization/colors-theme.mdx).
+- [Create consumers on login](../../dev-portal/dev-portal-create-consumer-on-auth.mdx)
+  if every signed-in user should receive a key automatically.
+- [Develop locally](./local.mdx) with live updates in your editor.

package/docs/{articles/step-3-add-api-key-auth.mdx → getting-started/gateway/add-api-key-auth/index.mdx}

@@ -1,11 +1,21 @@
 ---
-title: Step 3 - API Key Authentication
-sidebar_label: "3 - API Key Auth"
+category: API Management
+disablePager: true
+showLastModified: false
+suggestEdit: false
+title: Add API key authentication - Portal
+description:
+  Put API key authentication in front of your routes, issue a key to a consumer,
+  and reject calls that arrive without one in the Zuplo Portal.
 ---
 
+<WizardSteps build="gateway" method="portal" step="add-api-key-auth" />
+
+<MethodTabs build="gateway" method="portal" step="add-api-key-auth" />
+
 In this guide we'll add API Key authentication to a route. You can do this for
 any Zuplo project but will need a route, consider completing
-[Step 1](./step-1-setup-basic-gateway.mdx) first.
+[Step 1](../setup-a-basic-gateway/index.mdx) first.
 
 API Key authentication is one of our most popular **policies** as implementing
 this authentication method is considered one of the easiest to use by developers
@@ -14,10 +24,10 @@ other authentication methods.
 
 :::info{title="What's a Policy?"}
 
-[Policies](./policies.mdx) are modules that can intercept and transform an
-incoming request or outgoing response. Zuplo offers a wide range of policies
-built-in (including API key authentication) to save you time. You can check out
-[the full list](./policies.mdx).
+[Policies](../../../articles/policies.mdx) are modules that can intercept and
+transform an incoming request or outgoing response. Zuplo offers a wide range of
+policies built-in (including API key authentication) to save you time. You can
+check out [the full list](../../../articles/policies.mdx).
 
 :::
 
@@ -31,26 +41,26 @@ Let's get started.
    `routes.oas.json`) and open the **Policies** section. Then click **Add
    Policy**.
 
-   ![Add Policy](../../public/media/step-3-add-api-key-auth/image.png)
+   ![Add Policy](../../../../public/media/step-3-add-api-key-auth/image.png)
 
    Search for the API key authentication policy, click on it, and then click OK
    to accept the default policy JSON.
 
    <ModalScreenshot>
 
-   ![Add API Key Authentication](../../public/media/step-3-add-api-key-auth/choose-policy.png)
+   ![Add API Key Authentication](../../../../public/media/step-3-add-api-key-auth/choose-policy.png)
 
    </ModalScreenshot>
 
    :::tip
 
    The API key authentication policy should usually be one of the first policies
-   executed. If you came here from [Step 2](./step-2-add-rate-limiting.mdx) then
+   executed. If you came here from [Step 2](../add-rate-limiting/index.mdx) then
    you will want to drag it above the rate limiting policy.
 
    :::
 
-   ![reorder policies](../../public/media/step-3-add-api-key-auth/image-1.gif)
+   ![reorder policies](../../../../public/media/step-3-add-api-key-auth/image-1.gif)
 
    If you test your route, you should get a 401 Unauthorized response
 
@@ -68,11 +78,11 @@ Let's get started.
    [**Services**](https://portal.zuplo.com/+/account/project/services) tab in
    your project, then select **API Keys → Consumers** in the sidebar.
 
-   ![The API Keys → Consumers page in the Services section](../../public/media/step-3-add-api-key-auth/image-2.png)
+   ![The API Keys → Consumers page in the Services section](../../../../public/media/step-3-add-api-key-auth/image-2.png)
 
    Then click **Create Consumer**.
 
-   ![Create Consumer](../../public/media/step-2-add-api-key-auth/image-8.png)
+   ![Create Consumer](../../../../public/media/step-2-add-api-key-auth/image-8.png)
 
    Let's break down the configuration needed.
    - Subject: Also known as `sub`. This is a unique identifier of the API
@@ -90,7 +100,7 @@ Let's get started.
 
    <ModalScreenshot>
 
-   ![New Consumer](../../public/media/step-3-add-api-key-auth/image-3.png)
+   ![New Consumer](../../../../public/media/step-3-add-api-key-auth/image-3.png)
 
    </ModalScreenshot>
 
@@ -99,7 +109,7 @@ Let's get started.
    After your API Key consumer is created, copy your new API Key by clicking the
    copy button (next to the eye icon).
 
-   ![Copy Key](../../public/media/step-3-add-api-key-auth/image-4.png)
+   ![Copy Key](../../../../public/media/step-3-add-api-key-auth/image-4.png)
 
 4. Test out your API Key
 
@@ -108,7 +118,7 @@ Let's get started.
 
    <ModalScreenshot>
 
-   ![Failed unauthorized error](../../public/media/step-3-add-api-key-auth/test-policy.png)
+   ![Failed unauthorized error](../../../../public/media/step-3-add-api-key-auth/test-policy.png)
 
    </ModalScreenshot>
 
@@ -121,7 +131,7 @@ Let's get started.
 
    <ModalScreenshot>
 
-   ![successful response](../../public/media/step-3-add-api-key-auth/image-6.png)
+   ![successful response](../../../../public/media/step-3-add-api-key-auth/image-6.png)
 
    </ModalScreenshot>
 
@@ -130,7 +140,7 @@ Let's get started.
    We also offer an API for our API key service that allows you to
    programmatically create consumers and even create your own developer portal
    or integrate key management into your existing dashboard. See
-   [this document for details](./api-key-api.mdx).
+   [this document for details](../../../articles/api-key-api.mdx).
 
    :::
 
@@ -138,17 +148,17 @@ Let's get started.
 
    Whenever you deploy a new endpoint on Zuplo, it will automatically be added
    to your
-   [autogenerated developer documentation portal](../dev-portal/overview.mdx).
+   [autogenerated developer documentation portal](../../../dev-portal/overview.mdx).
 
    To access your API's developer portal, click the **Gateway deployed** button
    in your toolbar and click the link under Developer Portal.
-   ![Developer portal menu](../../public/media/step-2-add-rate-limiting/image-5.png)
+   ![Developer portal menu](../../../../public/media/step-2-add-rate-limiting/image-5.png)
 
    When you use certain policies like API keys, Zuplo will document properties
    like headers associated with that policy. As you can see on the right, the
    API key policy's `Authorization` header has been documented for you.
 
-   ![Developer Portal Endpoint](../../public/media/step-3-add-api-key-auth/image-7.png)
+   ![Developer Portal Endpoint](../../../../public/media/step-3-add-api-key-auth/image-7.png)
 
    Additionally, a new Authentication section has been added to your developer
    portal. Users of your API can sign in, view & manage their API keys, test
@@ -158,5 +168,4 @@ Let's get started.
 
 </Stepper>
 
-**NEXT** Try
-[Step 4 - Connect Source Control and Deploy to the Edge](./step-4-deploying-to-the-edge.mdx).
+<TutorialPager build="gateway" method="portal" step="add-api-key-auth" />

package/docs/{articles/step-3-add-api-key-auth-local.mdx → getting-started/gateway/add-api-key-auth/local.mdx}

@@ -1,11 +1,21 @@
 ---
-title: Step 3 - API Key Authentication
-sidebar_label: "3 - API Key Auth"
+category: API Management
+disablePager: true
+showLastModified: false
+suggestEdit: false
+title: Add API key authentication - Editor
+description:
+  Put API key authentication in front of your routes, issue a key to a consumer,
+  and reject calls that arrive without one with the Zuplo CLI and your editor.
 ---
 
+<WizardSteps build="gateway" method="local" step="add-api-key-auth" />
+
+<MethodTabs build="gateway" method="local" step="add-api-key-auth" />
+
 In this guide we'll add API Key authentication to a route. You can do this for
 any Zuplo project but will need a route, consider completing
-[Step 1](./step-1-setup-basic-gateway-local.mdx) first.
+[Step 1](../setup-a-basic-gateway/local.mdx) first.
 
 API Key authentication is one of our most popular **policies** as implementing
 this authentication method is considered one of the easiest to use by developers
@@ -14,10 +24,10 @@ other authentication methods.
 
 :::info{title="What's a Policy?"}
 
-[Policies](./policies.mdx) are modules that can intercept and transform an
-incoming request or outgoing response. Zuplo offers a wide range of policies
-built-in (including API key authentication) to save you time. You can check out
-[the full list](./policies.mdx).
+[Policies](../../../articles/policies.mdx) are modules that can intercept and
+transform an incoming request or outgoing response. Zuplo offers a wide range of
+policies built-in (including API key authentication) to save you time. You can
+check out [the full list](../../../articles/policies.mdx).
 
 :::
 
@@ -36,7 +46,7 @@ Let's get started.
 
    <BrowserScreenshot url="http://localhost:9100/?path=routes.oas.json">
 
-   ![Add Policy](../../public/media/step-3-add-api-key-auth-local/image.png)
+   ![Add Policy](../../../../public/media/step-3-add-api-key-auth-local/image.png)
 
    </BrowserScreenshot>
 
@@ -45,20 +55,19 @@ Let's get started.
 
    <ModalScreenshot>
 
-   ![Add API Key Authentication](../../public/media/step-3-add-api-key-auth/choose-policy.png)
+   ![Add API Key Authentication](../../../../public/media/step-3-add-api-key-auth/choose-policy.png)
 
    </ModalScreenshot>
 
    :::tip
 
    The API key authentication policy should usually be one of the first policies
-   executed. If you came here from
-   [Step 2](./step-2-add-rate-limiting-local.mdx) then you will want to drag it
-   above the rate limiting policy.
+   executed. If you came here from [Step 2](../add-rate-limiting/local.mdx) then
+   you will want to drag it above the rate limiting policy.
 
    :::
 
-   ![reorder policies](../../public/media/step-3-add-api-key-auth/image-1.gif)
+   ![reorder policies](../../../../public/media/step-3-add-api-key-auth/image-1.gif)
 
    If you test your route, you should get a 401 Unauthorized response
 
@@ -87,11 +96,11 @@ Let's get started.
 
    :::
 
-   ![The API Keys → Consumers page in the Services section](../../public/media/step-3-add-api-key-auth/image-2.png)
+   ![The API Keys → Consumers page in the Services section](../../../../public/media/step-3-add-api-key-auth/image-2.png)
 
    Then click **Create Consumer**.
 
-   ![Create Consumer](../../public/media/step-2-add-api-key-auth/image-8.png)
+   ![Create Consumer](../../../../public/media/step-2-add-api-key-auth/image-8.png)
 
    Let's break down the configuration needed.
    - Subject: Also known as `sub`. This is a unique identifier of the API
@@ -109,7 +118,7 @@ Let's get started.
 
    <ModalScreenshot>
 
-   ![New Consumer](../../public/media/step-3-add-api-key-auth/image-3.png)
+   ![New Consumer](../../../../public/media/step-3-add-api-key-auth/image-3.png)
 
    </ModalScreenshot>
 
@@ -118,7 +127,7 @@ Let's get started.
    After your API Key consumer is created, copy your new API Key by clicking the
    copy button (next to the eye icon).
 
-   ![Copy Key](../../public/media/step-3-add-api-key-auth/image-4.png)
+   ![Copy Key](../../../../public/media/step-3-add-api-key-auth/image-4.png)
 
 1. Test out your API Key
 
@@ -141,11 +150,10 @@ Let's get started.
    We also offer an API for our API key service that allows you to
    programmatically create consumers and even create your own developer portal
    or integrate key management into your existing dashboard. See
-   [this document for details](./api-key-api.mdx).
+   [this document for details](../../../articles/api-key-api.mdx).
 
    :::
 
 </Stepper>
 
-**NEXT** Try
-[Step 4 - Deploy to the Edge](./step-4-deploying-to-the-edge-local.mdx).
+<TutorialPager build="gateway" method="local" step="add-api-key-auth" />

package/docs/{articles/step-2-add-rate-limiting.mdx → getting-started/gateway/add-rate-limiting/index.mdx}

@@ -1,10 +1,20 @@
 ---
-title: Step 2 - Add Rate Limiting
-sidebar_label: "2 - Rate Limiting"
+category: API Management
+disablePager: true
+showLastModified: false
+suggestEdit: false
+title: Add rate limiting - Portal
+description:
+  Protect the gateway you just built by adding a rate limiting policy to a route
+  and watching it reject requests over the limit in the Zuplo Portal.
 ---
 
+<WizardSteps build="gateway" method="portal" step="add-rate-limiting" />
+
+<MethodTabs build="gateway" method="portal" step="add-rate-limiting" />
+
 In this guide we'll add simple Rate Limiting to a route. If you don't have one
-ready, complete [Step 1](./step-1-setup-basic-gateway.mdx) first.
+ready, complete [Step 1](../setup-a-basic-gateway/index.mdx) first.
 
 Rate Limiting is one of our most popular **policies** - you should never ship an
 API without rate limiting because your customers or internal developers **will**
@@ -12,10 +22,10 @@ accidentally DoS your API; usually with a rogue `useEffect` call in React code.
 
 :::info{title="What's a Policy?"}
 
-[Policies](./policies.mdx) are modules that can intercept and transform an
-incoming request or outgoing response. Zuplo offers a wide range of policies
-built-in (including rate limiting) to save you time. You can check out
-[the full list](../policies/overview.mdx).
+[Policies](../../../articles/policies.mdx) are modules that can intercept and
+transform an incoming request or outgoing response. Zuplo offers a wide range of
+policies built-in (including rate limiting) to save you time. You can check out
+[the full list](../../../policies/overview.mdx).
 
 :::
 
@@ -36,7 +46,7 @@ limiter.
 
    <ModalScreenshot>
 
-   ![Add policy](../../public/media/step-2-add-rate-limiting/image.png)
+   ![Add policy](../../../../public/media/step-2-add-rate-limiting/image.png)
 
    </ModalScreenshot>
 
@@ -44,7 +54,7 @@ limiter.
 
    <ModalScreenshot>
 
-   ![Add rate-limiting policy](../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
+   ![Add rate-limiting policy](../../../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
 
    </ModalScreenshot>
 
@@ -53,7 +63,7 @@ limiter.
    (`requestsAllowed`) every 1 minute (`timeWindowMinutes`). You can explore the
    rest of the policy's documentation and configuration in the right panel.
 
-   ![Rate limiting policy](../../public/media/step-2-add-rate-limiting/create-policy.png)
+   ![Rate limiting policy](../../../../public/media/step-2-add-rate-limiting/create-policy.png)
 
    To apply the policy, click **OK**. Then, save your changes to redeploy.
 
@@ -64,7 +74,7 @@ limiter.
 
    <ModalScreenshot>
 
-   ![429 response](../../public/media/step-2-add-rate-limiting/test-api.png)
+   ![429 response](../../../../public/media/step-2-add-rate-limiting/test-api.png)
 
    </ModalScreenshot>
 
@@ -73,5 +83,4 @@ limiter.
 
 </Stepper>
 
-**NEXT** Try
-[Step 3 - Add API Key Authentication](./step-3-add-api-key-auth.mdx).
+<TutorialPager build="gateway" method="portal" step="add-rate-limiting" />

package/docs/{articles/step-2-add-rate-limiting-local.mdx → getting-started/gateway/add-rate-limiting/local.mdx}

@@ -1,10 +1,21 @@
 ---
-title: Step 2 - Add Rate Limiting
-sidebar_label: "2 - Rate Limiting"
+category: API Management
+disablePager: true
+showLastModified: false
+suggestEdit: false
+title: Add rate limiting - Editor
+description:
+  Protect the gateway you just built by adding a rate limiting policy to a route
+  and watching it reject requests over the limit with the Zuplo CLI and your
+  editor.
 ---
 
+<WizardSteps build="gateway" method="local" step="add-rate-limiting" />
+
+<MethodTabs build="gateway" method="local" step="add-rate-limiting" />
+
 In this guide we'll add simple Rate Limiting to a route. If you don't have one
-ready, complete [Step 1](./step-1-setup-basic-gateway-local.mdx) first.
+ready, complete [Step 1](../setup-a-basic-gateway/local.mdx) first.
 
 Rate Limiting is one of our most popular **policies** - you should never ship an
 API without rate limiting because your customers or internal developers **will**
@@ -12,10 +23,10 @@ accidentally DoS your API; usually with a rogue `useEffect` call in React code.
 
 :::info{title="What's a Policy?"}
 
-[Policies](./policies.mdx) are modules that can intercept and transform an
-incoming request or outgoing response. Zuplo offers a wide range of policies
-built-in (including rate limiting) to save you time. You can check out
-[the full list](./policies.mdx).
+[Policies](../../../articles/policies.mdx) are modules that can intercept and
+transform an incoming request or outgoing response. Zuplo offers a wide range of
+policies built-in (including rate limiting) to save you time. You can check out
+[the full list](../../../articles/policies.mdx).
 
 :::
 
@@ -23,8 +34,8 @@ Zuplo offers a programmable approach to rate limiting that allows you to vary
 how rate limiting is applied for each customer or request.
 
 In this example, we'll add a simple IP-based rate limiter, but you should also
-explore [dynamic rate limiting](./step-5-dynamic-rate-limiting-local.mdx) to see
-the full power of the world's best rate limiter.
+explore [dynamic rate limiting](../dynamic-rate-limiting/local.mdx) to see the
+full power of the world's best rate limiter.
 
 <Stepper>
 
@@ -39,7 +50,7 @@ the full power of the world's best rate limiter.
 
    <BrowserScreenshot url="http://localhost:9100/?path=routes.oas.json">
 
-   ![Add Policy](../../public/media/step-2-add-rate-limiting-local/image.png)
+   ![Add Policy](../../../../public/media/step-2-add-rate-limiting-local/image.png)
 
    </BrowserScreenshot>
 
@@ -47,7 +58,7 @@ the full power of the world's best rate limiter.
 
    <ModalScreenshot>
 
-   ![Add rate-limiting policy](../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
+   ![Add rate-limiting policy](../../../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
 
    </ModalScreenshot>
 
@@ -56,7 +67,7 @@ the full power of the world's best rate limiter.
    (`requestsAllowed`) every 1 minute (`timeWindowMinutes`). You can explore the
    rest of the policy's documentation and configuration in the right panel.
 
-   ![Rate limiting policy](../../public/media/step-2-add-rate-limiting/create-policy.png)
+   ![Rate limiting policy](../../../../public/media/step-2-add-rate-limiting/create-policy.png)
 
    To apply the policy, click **Create Policy**, then save your changes.
 
@@ -91,5 +102,4 @@ the full power of the world's best rate limiter.
 
 </Stepper>
 
-**NEXT** Try
-[Step 3 - Add API Key Authentication](./step-3-add-api-key-auth-local.mdx).
+<TutorialPager build="gateway" method="local" step="add-rate-limiting" />