zuplo 7.1.1 → 7.1.2

package/docs/ai-gateway/managing-apps.mdx

@@ -1,12 +1,17 @@
 ---
 title: Managing Apps
+description:
+  Create, edit, and delete AI Gateway apps. Apps are created with just a name
+  and a team; models, budgets, and other behavior live on the app's policy
+  chain.
 ---
 
-Apps in the AI Gateway represent any app or integration that will call the AI
-Gateway. For example, you might have a custom support chatbot on your website -
-that chatbot would be an App in the AI Gateway. Each App has its own API Key so
-that usage is tracked independently. Apps are owned by a specific
-[team](./teams.mdx) and can access the AI Providers assigned to that team.
+An app represents one caller of your AI Gateway—a service, an agent, or a
+feature in a larger codebase. Each app has its own API key, which the gateway
+checks once you add the
+[authentication policy](./policy-chains.mdx#authentication); usage is tracked
+per app whether or not that policy applies. Each app belongs to a
+[team](./teams.mdx) and can reach the AI providers assigned to that team.
 
 ## Creating an App
 
@@ -21,28 +26,68 @@ that usage is tracked independently. Apps are owned by a specific
 
 1. Select the team that will own the app.
 
-1. Configure the AI Model that the app will use. You will select the provider,
-   model, and embedding model (if applicable).
-
-1. Optionally, you can set usage limits for the app. If you don't set limits,
-   the app will use the limits for the team.
-
 1. Click **Create**
 
 </Stepper>
 
+That's the whole dialog. The portal then takes you to the app's **Policies**
+tab. If the app's team defines a [policy template](./policy-templates.mdx), the
+new app starts with that chain; otherwise the chain is empty and the app is
+unrestricted until you add policies.
+
+## Restricting models
+
+By default an app isn't restricted to particular models: any model available
+through the providers assigned to the app's [team](./teams.mdx) is accepted. An
+unrestricted app has no default model, so every request must name one as
+`providerName/model`. A request with no model, or a model without that prefix,
+gets a `400`.
+
+To limit an app to specific models, add the **Model Filtering** policy to the
+app's [policy chain](./policy-chains.mdx)—models are controlled by that policy,
+not by the app's settings. Open the app's **Policies** tab, add Model Filtering,
+and configure each capability (completions, embeddings) in one of two modes:
+
+- An **allow list** exposes a curated set of models. Only listed models are
+  accepted, and the first entry is the default when a request doesn't specify a
+  model.
+- A **block list** permits every available model except the ones named. Each
+  request must name its model, because a block list supplies no default.
+
+The two modes are mutually exclusive per capability: a capability takes an allow
+list or a block list, never both.
+
+| Request                                                                                  | Response                      |
+| ---------------------------------------------------------------------------------------- | ----------------------------- |
+| A model the rules don't allow                                                            | `403`, listing what's allowed |
+| No `model` named, with no allow list to supply a default                                 | `400`                         |
+| A model with no `providerName/` prefix                                                   | `400`                         |
+| A capability the policy doesn't configure at all                                         | `403`                         |
+| A provider name that isn't in the project's [provider catalog](./managing-providers.mdx) | `400`                         |
+
+When model selection needs logic instead of a list, a custom policy can take
+over—see [Dynamic model routing](./cookbooks/dynamic-model-routing.mdx).
+
+## Setting budgets
+
+App budgets live on the **Budgets and Costs** policy in the app's chain. Open
+the app's **Policies** tab and configure it with daily or monthly limits for
+spending, tokens, or requests. If you don't set app limits, the team's and
+gateway's limits still apply. See [Usage Limits](./usage-limits.mdx).
+
 ## Editing an App
 
 To edit an app, open the
 [Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab of your AI
-Gateway project in the Zuplo Portal. Select the app you want to edit. Select the
-tab you want to edit (Policies or Settings). Make your changes and click the
-**Save** button.
+Gateway project in the Zuplo Portal. Select the app you want to edit. The app's
+behavior—models, budgets, caching, guardrails—is edited on the **Policies** tab;
+the app's name lives on the **Settings** tab. Make your changes and click the
+**Save** button. Policy chain changes apply within about a minute.
 
 ## Deleting an App
 
 To delete an app, open the
 [Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab of your AI
-Gateway project in the Zuplo Portal. Select the app you want to delete and
-scroll to the bottom of the page and click the **Delete App** button. You will
-be prompted to confirm the deletion.
+Gateway project in the Zuplo Portal. Select the app you want to delete, open its
+**Settings** tab, and click the **Delete App** button. You will be prompted to
+confirm the deletion.

package/docs/ai-gateway/managing-providers.mdx

@@ -1,11 +1,14 @@
 ---
 title: Managing AI Providers
 sidebar_label: Managing Providers
+description:
+  Add, edit, and delete AI providers in your AI Gateway project, and understand
+  how provider names become model references and when changes deploy.
 ---
 
 Zuplo's AI Gateway supports integration with various
 [AI providers](./providers.mdx), allowing you to leverage different models and
-services for your AI applications.
+services for your apps.
 
 ## Adding a New AI Provider
 
@@ -23,8 +26,11 @@ To add a new AI provider to your Zuplo AI Gateway, follow these steps:
    [supported providers](./providers.mdx), or
    [add a custom provider](./custom-providers.mdx).
 
-1. Specify a label for the provider instance to easily identify it later. You
-   can change the label later if required.
+1. Review the **Provider Name**, which fills in automatically based on the
+   provider you selected (a second OpenAI configuration becomes `openai-2`). You
+   can replace it with your own name, but only now—the name is permanent after
+   creation. Apps reference this provider's models as `providerName/model`—for
+   example, a provider named `openai` serves `openai/gpt-5-mini`.
 
 1. Enter the API Key for the selected provider. For instructions on how to
    create an API key for each provider see the
@@ -43,20 +49,30 @@ To add a new AI provider to your Zuplo AI Gateway, follow these steps:
 
 </Stepper>
 
+:::note
+
+Saving provider settings triggers an automatic production deployment of your
+gateway, because provider credentials are part of the deployed gateway. The
+change is live once the deployment completes.
+
+:::
+
 ## Editing an AI Provider
 
 To modify an existing provider, open
 [**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models)
 and click the **Edit** button next to the provider you want to modify.
 
-You can modify the label, API key, and selected models for the provider. After
-making your changes, click **Save** to apply them. Changes are effective
-immediately.
+You can modify the API key and selected models for the provider. The **Provider
+Name** isn't editable: it's the routing address in every `providerName/model`
+reference, so renaming it would orphan each stored reference to this provider.
+After making your changes, click **Save** to apply them.
 
 :::caution
 
 Be careful removing models from a provider that's in use as it may break
-existing applications that rely on the provider.
+existing apps that rely on the provider. Requests for a model that's no longer
+available fail with an error naming the model.
 
 :::
 

package/docs/ai-gateway/managing-teams.mdx

@@ -1,13 +1,21 @@
 ---
 title: Managing Teams
+description:
+  Create teams and sub-teams, add members, and set team-level policy templates
+  and usage limits in your AI Gateway project.
 ---
 
-Teams in the Zuplo AI Gateway are how users are granted access to AI Providers
-and Apps. Teams are hierarchical with access propagating downward. Teams are
-also where you define usage limits.
+Teams in the Zuplo AI Gateway are how users are granted access to AI providers
+and apps. Teams are hierarchical with access propagating downward. Teams are
+also where you define usage limits and
+[policy templates](./policy-templates.mdx).
 
 ## Creating a Team
 
+Creating a team requires admin rights: on the project for a top-level team, or
+on the parent team for a sub-team. Members without them see a disabled **Create
+Team** button.
+
 <Stepper>
 
 1. Open the [Teams](https://portal.zuplo.com/+/account/project/ai/teams) tab of
@@ -21,10 +29,18 @@ also where you define usage limits.
 
 </Stepper>
 
+After creating a team, use its tabs to configure it:
+
+- **Policies**—the team's [policy template](./policy-templates.mdx), the
+  starting policy chain for apps created in the team.
+- **Usage & Limits**—spending limits that apply to all of the team's apps
+  combined. See [Usage Limits](./usage-limits.mdx).
+- **Members**—who belongs to the team.
+
 ## Adding Team Members
 
-Team members are the users who belong to a team and can access the AI Providers
-and Apps associated with that team.
+Team members are the users who belong to a team and can access the AI providers
+and apps associated with that team.
 
 <Stepper>
 
@@ -42,15 +58,16 @@ and Apps associated with that team.
    don't have an account, they will be invited to join the account and then
    added to the team.
 
-1. Select the role for the user (if your plan supports RBAC). The available
-   roles are:
-   - **Member**: Can access AI Providers and Apps assigned to the team.
-   - **Admin**: Can manage team settings, members, and access AI Providers and
-     Apps assigned to the team.
+1. Select the role for the user:
+   - **Member**: Can access the AI providers and apps assigned to the team.
+   - **Admin**: Can manage team settings and members, and access the AI
+     providers and apps assigned to the team.
 
-     :::note
+     :::caution{title="The Member role requires RBAC"}
 
-     RBAC is an optional enterprise add-on. For more information see the
+     Role-based access control (RBAC) is an optional enterprise add-on on your
+     Zuplo account. Without it, only the **Admin** role is selectable—every user
+     you add to a team is an Admin. For more information see the
      [document on roles and permissions](../articles/accounts/roles-and-permissions.mdx).
 
      :::

package/docs/ai-gateway/policies/akamai-ai-firewall.mdx

@@ -1,125 +1,121 @@
 ---
 title: Akamai AI Firewall
 sidebar_label: Akamai AI Firewall
+description:
+  Scan prompts and completions with Akamai Firewall for AI and block what your
+  Akamai configuration denies.
 ---
 
-The Akamai AI Firewall policy integrates
-[Akamai Firewall for AI](https://www.akamai.com/products/firewall-for-ai) with
-the Zuplo AI Gateway, providing enterprise-grade security for AI-powered
-applications, large language models (LLMs), and AI-driven APIs.
+`akamai-ai-firewall-v2-inbound`
 
-The Akamai AI Firewall policy secures both inbound AI queries and outbound AI
-responses, protecting against emerging cyber threats specific to generative AI
-applications. By analyzing AI interactions in real-time, the policy detects and
-mitigates AI-specific vulnerabilities that traditional security tools can't
-address.
+The Akamai AI Firewall policy sends an app's prompts and completions to
+[Akamai Firewall for AI](https://www.akamai.com/products/firewall-for-ai) and
+blocks a request or response that your Akamai configuration denies. It's the
+gateway's guardrail policy: it can answer a request itself instead of letting it
+reach the provider.
+
+One entry covers both directions. The policy scans the prompt before the
+provider call and the completion afterward, including streaming
+responses—there's no separate outbound policy to add.
 
-### Key Security Capabilities
+Detection rules and their categories live in Akamai Control Center, not in
+Zuplo. The policy forwards text and enforces the decision that comes back,
+acting only on rules that deny. Rules set to alert are ignored.
 
-The Akamai AI Firewall provides comprehensive protection against AI-specific
-threats:
+## Adding the policy to an app
 
-- **Prompt injection defense**: Protects against attackers manipulating AI
-  models through deceptive inputs
-- **Data loss prevention (DLP)**: Detects and blocks sensitive data leaks in
-  AI-generated responses and incoming requests
-- **Toxic and harmful content filtering**: Flags hate speech, misinformation,
-  and offensive content before delivery
-- **Adversarial AI security**: Protects against remote code execution, model
-  back doors, and data poisoning attacks
-- **Denial-of-service mitigation**: Controls excessive query usage and model
-  overload
+<Stepper>
 
-## Benefits with Zuplo AI Gateway
+1. In your gateway's repository, set the policy's credentials and push:
 
-Integrating Akamai AI Firewall with the Zuplo AI Gateway provides several
-advantages:
+   ```json title="config/policies.json"
+   {
+     "name": "akamai-ai-firewall-v2-inbound",
+     "policyType": "akamai-ai-firewall-v2-inbound",
+     "handler": {
+       "export": "AkamaiAIFirewallV2InboundPolicy",
+       "module": "$import(@zuplo/runtime)",
+       "options": {
+         "configurationId": "your-configuration-id",
+         "api-key": "your-akamai-api-key"
+       }
+     }
+   }
+   ```
 
-### Unified Security Posture
+2. Open the app's **Policies** tab, click **Add Policy**, and add **Akamai AI
+   Firewall**. Leave the entry's options alone so it inherits the declaration's
+   configuration.
 
-Standardized AI security across your entire infrastructure, whether deployed at
-the edge, in the cloud, hybrid, or on-premises environments.
+</Stepper>
 
-### Automated Threat Detection
+To protect every new app in a team, add the policy to the team's
+[policy template](../policy-templates.mdx).
 
-AI-specific protections work automatically without manual rule tuning,
-leveraging Akamai's global threat intelligence to continuously adapt to emerging
-threats.
+## Options
 
-### Seamless WAAP Integration
+| Option                                  | Default    | What it does                                                                        |
+| --------------------------------------- | ---------- | ----------------------------------------------------------------------------------- |
+| `configurationId`                       | —          | Required. Your Akamai configuration                                                 |
+| `api-key`                               | —          | Required. Note the hyphen—`apiKey` is rejected                                      |
+| `applicationId`                         | —          | Optional Akamai application identifier                                              |
+| `endpoints`                             | All shapes | Which API shapes to inspect                                                         |
+| `onUnknownShape`                        | `deny`     | What to do with a request shape the policy can't read                               |
+| `streamingAccumulation.enabled`         | `true`     | Scan streaming completions. `false` stops scanning responses for streaming requests |
+| `streamingAccumulation.eventsInterval`  | `5`        | How many streamed events to buffer between checks                                   |
+| `streamingAccumulation.checkIntervalMs` | none       | Also check on a timer. Off unless set                                               |
 
-Extends web application and API protection (WAAP) capabilities with AI-specific
-defenses, providing comprehensive security for your API gateway.
+Unknown option keys are rejected.
 
-### Compliance and Governance
+## What a blocked caller sees
 
-Helps meet security and compliance standards including data privacy regulations,
-ethical AI usage requirements, and corporate governance mandates through
-detailed audit logs and real-time security analytics.
+A block returns `400` in the provider's own error format—not problem
+details—with the Akamai rule ID in `code`:
 
-### Zero Performance Impact
+```json
+{
+  "error": {
+    "message": "Request blocked by AI Firewall during completion request. <rule message> (Rule: <ruleId>)",
+    "code": "<ruleId>"
+  }
+}
+```
 
-The policy operates inline with minimal latency, preserving application
-performance while providing enterprise-grade security.
+For a streaming response, the gateway withholds output until each check passes,
+so blocked content never reaches the client. The stream then ends with a
+content-filter stop rather than an HTTP error, so clients see a content-filter
+finish reason. Holding events until a check returns adds to time to first token.
 
-## How It Works
+Blocked requests are counted against the app and appear in its Dashboard—see
+[Monitoring usage](../usage-limits.mdx#monitoring-usage).
 
-### AI Traffic Analysis
+## Failure modes
 
-The policy monitors and analyzes AI interactions by inspecting:
+| Situation                                                      | Result                                    |
+| -------------------------------------------------------------- | ----------------------------------------- |
+| Options are invalid or incomplete                              | Fails closed—request rejected             |
+| The request body can't be read                                 | Fails closed—request rejected             |
+| An endpoint shape the policy can't inspect, such as embeddings | `400`, code `guardrail_uninspectable`     |
+| Akamai is unreachable, or returns an error                     | **Fails open**—traffic proceeds unguarded |
 
-1. **Incoming user prompts**: Analyzed before reaching the AI model
-2. **AI-generated outputs**: Inspected before delivery to end users
+:::caution
 
-This dual-layer inspection prevents security risks while maintaining
-performance.
+Because the policy fails open, an expired Akamai key silently disables the
+firewall while the gateway keeps returning `200`s. Monitor blocked counts so a
+sudden drop to zero doesn't go unnoticed.
 
-### Risk Scoring
+:::
 
-AI interactions are evaluated against multiple security indicators, including:
+An endpoint the policy can't inspect is denied by default. That's different from
+an endpoint you exclude with `endpoints`, which passes through silently. A
+provider error response is never scanned.
+
+If a request is rejected with a configuration error, the usual cause is a chain
+entry that overrode `options` and dropped the credential—entry options replace
+the declared ones wholesale rather than merging. Omit them to inherit. See
+[Options and secrets](../policy-chains.mdx#options-and-secrets).
+
+## Additional resources
 
-- Prompt injection attempts
-- Sensitive data exposure
-- Adversarial exploits
-- Toxic content patterns
-- Abnormal query patterns
-
-### Security Enforcement Actions
-
-Based on risk scores and configured policies, the firewall takes one of three
-actions:
-
-- **Monitor**: Logs detected threats for analysis without interfering with AI
-  queries or responses
-- **Modify**: Adjusts AI-generated outputs inline, removing or altering unsafe
-  content while maintaining natural conversation flow
-- **Deny**: Blocks high-risk inputs from reaching the AI model and prevents
-  unsafe responses from being returned to users
-
-## Use Cases
-
-### Protecting Customer-Facing AI Chatbots
-
-Secure AI-powered customer service applications from prompt injection attacks
-and ensure responses don't leak sensitive customer data or generate toxic
-content.
-
-### Safeguarding Internal AI Tools
-
-Protect internal AI assistants and copilots from adversarial exploits while
-preventing unauthorized access to proprietary information.
-
-### Regulatory Compliance
-
-Maintain compliance with data protection regulations (GDPR, CCPA, etc.) by
-automatically detecting and blocking sensitive data leaks in AI interactions.
-
-### API Security for AI Services
-
-Extend your API security posture to cover AI-specific threats that traditional
-API gateways can't detect.
-
-**Additional Resources**
-
-- [Akamai Firewall for AI Product Page](https://www.akamai.com/products/firewall-for-ai)
-- [Akamai AI Security Solutions](https://www.akamai.com/solutions/security/ai-security)
+- [Akamai Firewall for AI](https://www.akamai.com/products/firewall-for-ai)
+- [Akamai AI security solutions](https://www.akamai.com/solutions/security/ai-security)

package/docs/ai-gateway/policies/authentication.mdx

@@ -0,0 +1,44 @@
+---
+title: API key authentication
+sidebar_label: API key authentication
+description:
+  Require an app's API key on every request and resolve the calling app from it.
+---
+
+`ai-gateway-auth-v2`
+
+Clients send the app's API key as a bearer token, and the gateway resolves the
+calling app from the key. A missing or invalid key returns `401`. A valid key
+whose app doesn't match the `{app_id}` in the URL returns `403`.
+
+The policy applies per app: in an app's chain, it requires a key for that app
+alone. A new team's [policy template](../policy-templates.mdx) includes it as a
+locked entry, so apps created in the team require keys from the start. Placed on
+the gateway's route instead—before the Configuration Executor, in the gateway's
+repository—one entry requires a key for every app on that route.
+
+## Options
+
+| Option            | Default         | What it does                                                      |
+| ----------------- | --------------- | ----------------------------------------------------------------- |
+| `cacheTtlSeconds` | `10`            | How long the gateway caches a key check. `10` is also the minimum |
+| `authHeader`      | `Authorization` | The header to read the key from                                   |
+| `authScheme`      | `Bearer`        | The scheme prefix. Set it to `""` to use the raw header value     |
+
+For clients that send `x-api-key` instead of a bearer token, use
+`{ "authHeader": "x-api-key", "authScheme": "" }`.
+
+Because key checks are cached, a revoked key can keep working until the cache
+expires.
+
+:::caution{title="A gateway without this policy is open"}
+
+When the policy sits neither on the route nor in an app's chain, the gateway
+resolves the app from the `{app_id}` segment of the URL and serves the request
+with no key at all. Anyone who knows the URL can spend against the app's
+providers and budget. Only run an open gateway when something else, such as
+network isolation, controls who can reach it.
+
+:::
+
+Each app's key appears on its app page—see [Apps](../apps.mdx).

package/docs/ai-gateway/policies/comet-opik-tracing.mdx

@@ -1,6 +1,9 @@
 ---
-title: Comet Opik Tracing
-sidebar_label: Comet Opik Tracing
+title: Comet Opik tracing
+sidebar_label: Comet Opik tracing
+description:
+  Send LLM traces from the Zuplo AI Gateway to Comet Opik for observability,
+  debugging, and evaluation of your AI applications.
 ---
 
 The Comet Opik Tracing policy integrates
@@ -30,6 +33,41 @@ features:
 - **High-volume ingestion**: Support for up to 40 million traces per day
 - **Dataset management**: Store and run evaluations on test datasets
 
+## Adding the policy to an app
+
+The scaffolded gateway declares the Comet Opik Tracing policy in
+`config/policies.json`. Configure it once for the gateway, then add it to each
+app that should send traces:
+
+<Stepper>
+
+1. In your Comet account, create (or pick) a project and workspace and generate
+   an API key.
+
+2. In your gateway's repository, set the policy's settings and push:
+
+   ```json title="config/policies.json"
+   {
+     "name": "comet-opik-tracing-v2-inbound",
+     "policyType": "comet-opik-tracing-v2-inbound",
+     "handler": {
+       "export": "CometOpikTracingV2InboundPolicy",
+       "module": "$import(@zuplo/runtime)",
+       "options": {
+         "apiKey": "your-opik-api-key",
+         "projectName": "your-project-name",
+         "workspace": "your-workspace"
+       }
+     }
+   }
+   ```
+
+3. Open the app's **Policies** tab, click **Add Policy**, and add **Comet Opik
+   Tracing**. Place it at the end of the chain so traces reflect the request the
+   provider actually receives.
+
+</Stepper>
+
 ## Benefits with Zuplo AI Gateway
 
 Integrating Comet Opik with the Zuplo AI Gateway provides several advantages:

package/docs/ai-gateway/policies/fallback-model.mdx

@@ -0,0 +1,40 @@
+---
+title: Fallback Model
+sidebar_label: Fallback Model
+description:
+  Add a backup model for provider errors and timeouts, and a cheaper model for
+  when a budget runs out.
+---
+
+`ai-gateway-fallback-model-v2`
+
+Fallback Model adds two kinds of backup to an app's model selection, per
+capability:
+
+- **`fallback`**—the model to try after a provider error that can be retried, or
+  after a timeout.
+- **`quotaFallback`**—the model to use when a usage limit is hit, instead of
+  rejecting the request. [Budgets and Costs](./metering.mdx) is what applies
+  this.
+
+`fallbackTimeoutSeconds` controls how long the gateway waits before giving up on
+the main model and trying the fallback. It defaults to 60 seconds and accepts 1
+to 300. A fallback that names the same model as the main one is skipped.
+
+:::warning
+
+This policy only enriches a model selection that already exists—it never creates
+one. An app whose chain has Fallback Model but no
+[Model Filtering](./model-filtering.mdx) does nothing at all: the policy logs a
+warning and passes the request through unchanged. Place Fallback Model
+immediately after Model Filtering.
+
+:::
+
+That ordering is also why a fallback can never widen what an app may reach—the
+filter has already accepted or rejected the request by the time this policy
+runs.
+
+For the portal workflow and worked examples see
+[Fallback Models](../fallback.mdx); for every option see the
+[generated reference](/policies/ai-gateway-fallback-model-v2-inbound).