zuplo 6.67.32 → 6.68.0

package/docs/dedicated/federated-gateways.mdx

@@ -0,0 +1,80 @@
+---
+title: "Managed Dedicated: Federated Gateways"
+sidebar_label: Federated Gateways
+---
+
+:::note{title="Beta Feature"}
+
+This feature is in Beta - please use with care and provide feedback to the team
+if you encounter any issues.
+
+:::
+
+<EnterpriseFeature name="Federated Gateways" />
+
+With a managed dedicated Zuplo instance you can create a federated gateway that
+allows you to connect multiple Zuplo projects together. This is useful for
+creating a single API Gateway that can route requests to multiple backend
+services, each running on its own Zuplo instance.
+
+## Reasons to Use Federated Gateways
+
+Federated gateways are useful for several reasons:
+
+- **Separation of Product Areas**: Depending on your organizational structure,
+  you may want to separate different product areas into their own Zuplo
+  projects. This allows teams to work independently while still being able to
+  route requests through a single gateway. Each team can manage their own
+  portion of the API without affecting others. Each team creates its own Zuplo
+  Project with its own git repository, environment variables, etc.
+- **Versioning**: You can use federated gateways to manage different versions of
+  your API. For example, if you wanted to run a new version of your API
+  alongside the old one and route requests to specific versions based on user or
+  other context you can keep different versions in separate Zuplo projects.
+- **Risk Minimization**: By separating different parts of your API into
+  different Zuplo projects, you can reduce the risk of causing inadvertent
+  changes to other parts of the API. This can be especially useful if your API
+  is particularly large or complex.
+
+## How to Create a Federated Gateway
+
+Managed dedicated Zuplo environments can call other Zuplo environments deployed
+in the same instance. To make a call to another Zuplo environment, you simply
+make a normal HTTP request to the other environment using the URL protocol
+`local` with the environment name. For example, if your environment is named
+`my-api-main-2s93j2`, then you would make a request to
+`local://my-api-main-2s93j2`.
+
+You can use most Zuplo request handlers to make these requests (the Lambda
+handler isn't supported).
+
+For example, to create a federated gateway that forwards requests to another
+Zuplo environment, you can use the URL Forward handler. Here is an example
+configuration for a route that forwards requests to another Zuplo environment:
+
+```json
+{
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "baseUrl": "local://my-api-main-2s93j2"
+    }
+  }
+}
+```
+
+:::caution
+
+Currently, federated gateways are still exposed externally, so you should ensure
+that you have proper authentication and authorization in place to prevent
+unauthorized access to your federated gateway.
+
+This can be done using the standard Zuplo authentication and authorization
+mechanisms, such as API keys, JWTs, or OAuth2.
+
+Soon you will be able to restrict access to federated gateways, which will make
+it easier to secure your federated gateway without needing to implement
+additional authentication mechanisms.
+
+:::

package/docs/dedicated/networking.mdx

@@ -0,0 +1,69 @@
+---
+title: "Managed Dedicated: Networking"
+sidebar_label: Networking
+---
+
+Your dedicated managed instance of Zuplo will be deployed to the cloud provider
+of your choice. Network connectivity can be customized to meet your specific
+requirements.
+
+Common configurations include:
+
+- Using Zuplo as the public ingress to your API and using network connectivity
+  such as AWS Transit Gateway, PrivateLink, or VPC Peering to connect to your
+  backend services.
+- Restricting access to the public internet by configuring your API Gateway to
+  only accept traffic from specific IP ranges or VPCs allowing you to put WAFs,
+  IDS/IPS, or other security appliances in front of your API Gateway.
+- Multiple dedicated managed instances of Zuplo can be deployed across multiple
+  regions to provide high availability and disaster recovery.
+
+To discuss your networking requirements, please contact your account manager.
+
+## Zuplo Ingress to Customer VPC
+
+The default setup for dedicated managed Zuplo is to use your Zuplo API Gateway
+as the public ingress to your API. This is the simplest setup and allows Zuplo
+to manage things like SSL certificates on your behalf.
+
+In this setup your VPC isn't exposed to the public internet at all. Instead,
+your Zuplo API Gateway will use a network connection such as AWS Transit
+Gateway, PrivateLink, or VPC Peering to connect to your backend services.
+
+<Diagram height="h-48">
+  <DiagramNode id="client">Client</DiagramNode>
+  <DiagramGroup id="dedicated-vpc" label="Dedicated VPC">
+    <DiagramNode id="gateway" variant="zuplo">
+      Zuplo API Gateway
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramGroup id="customer-vpc" label="Customer VPC">
+    <DiagramNode id="backend">Backend</DiagramNode>
+  </DiagramGroup>
+  <DiagramEdge from="client" to="gateway" />
+  <DiagramEdge from="gateway" to="backend" />
+</Diagram>
+
+## Customer VPC Ingress to Zuplo API Gateway
+
+If you have custom networking requirements, such as using a static IP address
+you already own, or if you want to run services such as WAFs, IDS/IPS, or other
+security products in front of your API Gateway, Zuplo can be configured to
+accept traffic from your VPC then route it to your backend. Your backend could
+be in the same VPC as your ingress or in another VPC.
+
+<Diagram height="h-64">
+  <DiagramNode id="client">Client</DiagramNode>
+  <DiagramGroup id="customer-vpc" label="Customer VPC">
+    <DiagramNode id="waf">WAF</DiagramNode>
+    <DiagramNode id="backend">Backend</DiagramNode>
+  </DiagramGroup>
+  <DiagramGroup id="dedicated-vpc" label="Dedicated VPC">
+    <DiagramNode id="gateway" variant="zuplo">
+      Zuplo API Gateway
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramEdge from="client" to="waf" />
+  <DiagramEdge from="waf" to="gateway" />
+  <DiagramEdge from="gateway" to="backend" fromSide="left" toSide="right" />
+</Diagram>

package/docs/dedicated/overview.mdx

@@ -0,0 +1,80 @@
+---
+title: Zuplo Managed Dedicated
+sidebar_label: Overview
+---
+
+Zuplo Managed Dedicated is a deployment model where Zuplo runs one or more
+instances of the Zuplo platform on the hosting provider of your choice. This
+deployment model is ideal for organizations that require custom networking
+configurations or have strict security or compliance requirements.
+
+Managed Dedicated hosting might be the right choice for you if you need:
+
+- To run your API Gateway on the cloud provider of your choice
+- To customize networking configurations, such as restricting access to the
+  public internet
+- Have geographical deployment requirements where the
+  [Managed Edge](../articles/hosting-options.mdx#1-managed-edge) hosting option
+  isn't feasible
+- Have regulatory or compliance requirements that necessitate a dedicated
+  instance of Zuplo
+- To meet data sovereignty requirements by choosing specific regions for your
+  service hosting
+
+## Cloud Providers
+
+Zuplo Managed Dedicated can be deployed on a wide range of cloud providers and
+hosting platforms, including:
+
+- **Akamai Connected Cloud** - Leverage Akamai's global network infrastructure
+- **AWS** - Deploy to Amazon Web Services with full VPC integration
+- **Azure** - Run on Microsoft Azure with private networking support
+- **GCP** - Deploy to Google Cloud Platform with custom networking
+- **Equinix** - Use Equinix data centers for colocation and connectivity
+- **TerraSwitch** - Deploy to TerraSwitch infrastructure
+- **Other providers** - Contact us to discuss support for additional providers
+
+You can choose the regions where you want your service hosted to meet any
+sovereignty or data residency concerns.
+
+## Features
+
+The managed dedicated hosting model provides the same core features as other
+Zuplo deployment models. You can use all the same policies, integrations, and
+features as you would with edge-based deployments.
+
+### Networking and Security
+
+In addition to the standard features, managed dedicated hosting provides:
+
+- **Custom Networking Configurations** - Configure your API Gateway to only be
+  accessible from specific VPCs or IP ranges
+- **Private Networking Options** - Support for AWS PrivateLink, Azure Private
+  Link, and GCP Private Service Connect for both inbound and outbound
+  connections
+- **Isolated VPC Deployment** - Your gateway runs in a dedicated, isolated VPC
+  for maximum security and isolation
+- **Custom Ingress Options** - Use your own static IP addresses or security
+  appliances (WAFs, IDS/IPS) in front of your API Gateway
+
+### High Availability
+
+- **Multi-Region Deployment** - Deploy multiple dedicated instances across
+  multiple regions for high availability and disaster recovery
+- **Automatic Failover** - Configure automatic failover between regions
+- **Custom Availability Zones** - Choose specific availability zones to meet
+  your redundancy requirements
+
+### Control and Compliance
+
+- **Dedicated Instance** - Your own isolated instance of Zuplo, ensuring no
+  resource sharing with other customers
+- **Full Feature Parity** - Access to all Zuplo policies, integrations, and
+  features
+- **Compliance Support** - Meet regulatory and compliance requirements that
+  necessitate dedicated infrastructure
+
+## Getting Started
+
+To learn more about Zuplo Managed Dedicated or to discuss your specific
+requirements, [schedule some time to talk with us](https://book.zuplo.com).

package/docs/dedicated/source-control.mdx

@@ -0,0 +1,63 @@
+---
+title: "Managed Dedicated: Source Control"
+sidebar_label: "Source Control"
+---
+
+Zuplo supports GitOps workflows for managing your API Gateway configuration.
+This means that you can store all of your API Gateway configuration in a Git
+repository and use Git to manage changes to your configuration. This allows you
+to track changes to your configuration over time, collaborate with others, and
+easily roll back changes if needed.
+
+You will use the Zuplo CLI to deploy your API using CI/CD pipelines or using one
+of the Zuplo's [Git integrations](../articles/source-control.mdx).
+
+## Create a Local Project
+
+To begin developing your API, you will need to create a local project. You can
+find the full documentation for
+[local development here](../articles/local-development.mdx).
+
+```bash
+npx create-zuplo-api@latest
+```
+
+This command will prompt you to enter a project name and options for your
+project.
+
+## Create a Git Repository
+
+Next, you will need to create a Git repository to store your API Gateway
+configuration. You can use a service like GitHub, GitLab, or Bitbucket to create
+a new repository.
+
+Your new Zuplo project is already initialized as a git repo, so you just need to
+add a remote repository and push your changes.
+
+```bash
+git remote add origin https://github.com/my-org/my-repo
+git commit -m "Initial commit"
+git push -u origin main
+```
+
+## GitHub: Connect Zuplo to your Repository
+
+If you are using GitHub, you can connect your Zuplo project to your GitHub
+repository using the Zuplo integration. This will configure Zuplo to
+automatically deploy your API Gateway when you push changes to your repository.
+
+For the full instructions on how to connect your Zuplo project to GitHub, see
+[GitHub Integration](../articles/source-control-setup-github.mdx).
+
+## Custom CI: Deploy your API
+
+If you aren't using GitHub, or would like to set up a custom CI/CD pipeline, you
+can use the Zuplo CLI to deploy your API Gateway.
+
+```bash
+npx zuplo deploy --api-key $ZUPLO_API_KEY --project your-project-name --environment my-env
+```
+
+For more information on setting up a CI/CD pipeline, see
+[CI/CD](../articles/custom-ci-cd.mdx) and the
+[Zuplo CLI Deployment](../cli/deploy.mdx) docs.

package/docs/dev-portal/dev-portal-create-consumer-on-auth.mdx

@@ -0,0 +1,134 @@
+---
+title: Create an API Key Consumer on Login
+sidebar_label: Create API Key on Auth
+navigation_icon: id-card-lanyard
+description:
+  Learn how to automatically create an API Key Consumer for users upon login to
+  your Developer Portal using Auth0 actions. This guide provides step-by-step
+  instructions for integrating with the Dev Portal.
+---
+
+By default, users who log into your Zuplo powered Developer Portal won't have an
+API Consumer. This is by design as it allows you to control who has access to
+your API, what their permissions or quotas are, etc. However, some APIs are open
+to any user who can login. This might mean you let anyone login and create an
+account or it might mean you use authorization policies with your identity
+provider to control who can access the portal.
+
+This article explains how to use Auth0 actions to automatically create an API
+Key Consumer for your users when they sign into your developer portal.
+
+:::tip
+
+You don't need to set this up if using the built-in Zuplo monetization feature.
+We do this all for you in that flow.
+
+:::
+
+Before you begin, you will need to
+[set up custom authentication](./zudoku/configuration/authentication.mdx) for
+the developer portal - you can't use the built-in "demo" provider for this
+tutorial.
+
+To begin, open the [Auth0 management portal](https://manage.auth0.com) and
+navigate to **Actions** > **Library**. Then click the button **Build Custom**.
+
+Set a name for your custom action and select the **Login / Post Login** trigger.
+Select Node.js version 16 or greater.
+
+![Create an action](../../public/media/dev-portal-create-consumer-on-auth/a46eabb3-4c22-476b-acc3-c5ab330d451e.png)
+
+Next, add the Node module [`undici`](https://www.npmjs.com/package/undici) as a
+package to the custom action. To open the module editor click the box icon on
+the side bar, then click **Add Dependency**. Enter the name `undici` and a
+specific version of the module, in this case `5.22.1`. Click **Create** when
+finished.
+
+![Add dependency](../../public/media/dev-portal-create-consumer-on-auth/0daf1916-3fac-4bed-b00d-55694236619c.png)
+
+In order to authenticate to Zuplo's Developer API, you will need to get your API
+Key. See [Account API Keys](../articles/accounts/zuplo-api-keys.mdx) for
+instructions on finding your API Key. Once you have retrieved your secret, click
+the key icon on the Auth0 editor sidebar and click **Add Secret**. Name the
+secret `API_KEY` and set the value.
+
+![Define a secret](../../public/media/dev-portal-create-consumer-on-auth/2cf32602-9716-4b8d-9641-3830500e01c1.png)
+
+:::info
+
+In the code below set the variable `BUCKET_NAME` to the bucket being used by
+your Zuplo Gateway. If you don't know the name of your bucket, you can
+[list your buckets using the Developer API](https://dev.zuplo.com/docs/routes#apikeybucketsservice_list).
+
+:::
+
+Next, add the following code to your custom action. Be sure to replace the
+placeholder values with your actual account and bucket names. Click the
+**Deploy** button when you are finished.
+
+```ts
+const { fetch } = require("undici");
+const { randomUUID } = require("crypto");
+
+const ZUPLO_ACCOUNT = "my-zuplo-account";
+const API_KEY_BUCKET = "my-bucket";
+
+/**
+ * Handler that will be called during the execution of a PostLogin flow.
+ *
+ * @param {Event} event - Details about the user and the context in which they are logging in.
+ * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
+ */
+exports.onExecutePostLogin = async (event, api) => {
+  if (event.user.app_metadata.api_consumer) {
+    console.log(
+      `Skipping creating of API consumer. Already exists: ${event.user.app_metadata.api_consumer}`,
+    );
+    return;
+  }
+
+  const body = {
+    description: `Consumer for ${event.user.name}`,
+    managers: [event.user.email],
+    metadata: {
+      // Any metadata here
+      user_id: event.user.user_id,
+    },
+    name: `c-${randomUUID()}`,
+  };
+
+  try {
+    // Create the consumer
+    const response = await fetch(
+      `https://dev.zuplo.com/v1/accounts/${ZUPLO_ACCOUNT}/key-buckets/${API_KEY_BUCKET}/consumers?with-api-key=true`,
+      {
+        method: "POST",
+        body: JSON.stringify(body),
+        headers: {
+          Authorization: `Bearer ${event.secrets.API_KEY}`,
+          "content-type": "application/json",
+        },
+      },
+    );
+    const result = await response.json();
+    if (response.status !== 200) {
+      console.error(result);
+      throw new Error("Error creating API consumer");
+    }
+    // Set the consumer in the user's metadata
+    api.user.setAppMetadata("api_consumer", result.id);
+  } catch (err) {
+    // Catching error to not block the user's login to the portal
+    console.error(err);
+  }
+};
+```
+
+Last, on the Auth0 side navigation bar, open **Actions** > **Flows**, then
+select **Login**. Add the action to the workflow by selecting **Custom** and
+dragging your custom action to the flow and then click **Apply**.
+
+![Applying the action](../../public/media/dev-portal-create-consumer-on-auth/a928c966-1636-47ad-af23-9f265e9eb590.png)
+
+Now, login to your developer portal with a new user and you will see a consumer
+has already been created.

package/docs/dev-portal/introduction.mdx

@@ -0,0 +1,65 @@
+---
+title: Introduction
+description: Introduction to Zuplo's beautiful, auto-generated developer portal.
+---
+
+Every API deserves beautiful and powerful documentation. The Zuplo Developer
+Portal powers this documentation site and is available for all Zuplo users.
+
+![Zuplo Dev Portal](../../public/media/introduction/image-1.png)
+
+## What is the Dev Portal?
+
+The Developer Portal is a powerful tool that allows you to create and manage
+beautiful API documentation. It is built on top of the Zuplo platform and
+provides a seamless experience for developers to consume your APIs.
+
+## Why the new Dev Portal?
+
+The new Developer Portal is rewritten from the ground up to provide a more
+customizable experience. It is easy to use out of the box, but also allows for
+advanced customization for those who want to take it to the next level. The new
+Developer Portal is built on top of Zudoku, which is a powerful static site
+generator that allows for advanced customization and theming. Zudoku is built on
+Vite which allows for fast builds and a great developer experience.
+
+## What Features are available?
+
+The new Developer Portal is packed with features that make it easy to create and
+manage your API documentation. Some of the key features include:
+
+- **Markdown Documentation**: Write your documentation in Markdown and have it
+  automatically converted to HTML.
+- **API Documentation**: Automatically generate API documentation from your
+  OpenAPI specifications.
+- **API Explorer**: Explore and test your API directly from the documentation.
+- **Custom Pages**: Create custom pages for your documentation using Markdown,
+  MDX, or even React.
+- **Custom Modules**: Install custom modules to extend the functionality of your
+  documentation.
+- **API Key Management**: When using Zuplo's API Key management, manage API keys
+  directly from the documentation.
+- **Built-in Analytics**: End users can see how they are using the API, monitor
+  usage of their API keys, and more right from inside the portal.
+
+## How to get started?
+
+To get started, sign up for a Zuplo account and create a new project. Follow the
+[migration guide](./migration.mdx) to enable the Developer Portal on an existing
+project.
+
+## Build, Deploy, and Hosting
+
+Zuplo manages the build, deploy, and hosting of your developer portal for you.
+Simply sign up for Zuplo, create a new project, and you will have a fully
+functioning developer portal in minutes. Zuplo handles all the hosting and
+deployment for you, so you can focus on building your API and documentation.
+
+You can also configure a custom domain for your Developer Portal to match your
+brand. Learn more in the
+[Custom Domains documentation](/docs/articles/custom-domains).
+
+## Feedback
+
+The Developer Portal is continuously improving. For suggestions or feedback,
+email [support@zuplo.com](mailto:support@zuplo.com).

package/docs/dev-portal/local-development.mdx

@@ -0,0 +1,72 @@
+---
+title: Local Development
+description:
+  Learn how to work on the Dev Portal locally with live updates and hot
+  reloading.
+---
+
+Developing the Dev Portal locally is straightforward and provides a great
+developer experience with live updates and hot reloading. Follow these steps to
+get started.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) `>=v22.7.0` (or `>=20.19` will work as well)
+- [Git](https://git-scm.com)
+
+## Getting Started
+
+<Stepper>
+
+1. **Clone the Zuplo repository**
+
+   ```bash
+   git clone <repository-url>
+   ```
+
+1. **Install dependencies**
+
+   ```bash
+   npm install
+   ```
+
+1. **Navigate to the docs directory**
+
+   ```bash
+   cd docs
+   ```
+
+1. **Start the development server**
+
+   ```bash
+   npm run dev
+   ```
+
+1. **Open your browser**
+
+   Navigate to [http://localhost:3000](http://localhost:3000) to see your Dev
+   Portal.
+
+</Stepper>
+
+## Development Workflow
+
+Once the development server is running, you can:
+
+- **Edit content**: Make changes to any Markdown, MDX, or configuration files
+- **Live updates**: Your browser will automatically refresh when you save
+  changes
+- **Hot reloading**: Most changes will be reflected instantly without a full
+  page reload
+- **Real-time feedback**: See your changes immediately as you develop
+
+The development server watches for file changes and automatically rebuilds the
+site, providing an excellent developer experience for creating and maintaining
+your documentation.
+
+## What's Next?
+
+- Learn about [writing content](./zudoku/writing.mdx)
+- Check out [the configuration file](./zudoku/configuration/overview)
+- See how you can
+  [customize the Dev Portal](./zudoku/customization/colors-theme)