zuplo 6.69.4 → 6.69.5

package/docs/articles/when-to-use-api-keys.md

@@ -0,0 +1,191 @@
+---
+title: When to Use API Keys
+sidebar_label: When to Use Them
+---
+
+Choosing the right authentication method is one of the first decisions you make
+when building an API. This guide explains when API keys are the right choice,
+when they are not, and how they compare to JWT and OAuth.
+
+## API keys vs JWT vs OAuth
+
+API keys, JWTs, and OAuth solve different problems. Picking the wrong one
+creates friction for your consumers or security gaps in your API.
+
+|                          | API Keys                                                        | JWT (self-issued)                                                  | OAuth 2.0                                                        |
+| ------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| **Identifies**           | An organization, system, or service                             | A user or service (claims embedded in token)                       | A user acting through a third-party app                          |
+| **Credential format**    | Opaque string - no embedded data                                | Encoded JSON with claims (readable by anyone)                      | Access token issued by an authorization server                   |
+| **Revocation**           | Instant - delete the key and it stops working                   | Not instant - valid until expiry (unless you maintain a blocklist) | Depends on token lifetime and refresh flow                       |
+| **Developer experience** | Single string in a header, works in curl                        | Requires token generation, sometimes a signing key                 | Requires redirect flow, client registration, token exchange      |
+| **Best for**             | Server-to-server integrations, developer platforms, public APIs | Internal service-to-service auth, short-lived sessions             | User-facing apps that need delegated access ("act on behalf of") |
+
+:::note
+
+API key authentication, like all bearer token authentication, requires HTTPS in
+production. Without TLS, keys are transmitted in plaintext and can be
+intercepted in transit.
+
+:::
+
+### When to use API keys
+
+API keys are the right choice when your API consumers are **organizations,
+services, or developers integrating server-to-server** - not individual
+end-users acting on their own behalf.
+
+This is why the most successful API-first companies use API keys:
+
+- **Stripe** - every API call uses an API key scoped to the organization
+- **Twilio** - Account SID + Auth Token (functionally an API key pair)
+- **Resend** - API keys with scoped permissions per key
+- **Datadog, Cloudflare, PagerDuty** - all use API keys for their public APIs
+
+Use API keys when:
+
+- Your consumers are developers integrating with your API from their backend
+- You want the simplest possible developer experience - a single string, no
+  token refresh, works in curl
+- You need to identify and rate-limit individual consumers or organizations
+- You want the ability to revoke access instantly (unlike JWTs, which remain
+  valid until they expire)
+- You are building a developer platform, partner API, or public API
+
+:::warning
+
+Do not embed API keys in frontend JavaScript, mobile apps, or any client-side
+code. Keys in client bundles are trivially extractable and cannot be scoped to a
+user session. Use OAuth for scenarios where individual end-users authenticate
+from a browser or device.
+
+:::
+
+### When to use JWT or OAuth
+
+Use JWT or OAuth when:
+
+- You need to authenticate **on behalf of an individual end-user** (the redirect
+  and consent flow - often called the "OAuth dance" - exists for this reason)
+- Your use case requires **delegated authorization with scoped permissions**
+  (e.g., "this app can read my repos but not delete them")
+- You are building a **user-facing login flow** where the user interacts with
+  your auth provider directly
+
+### Quick decision checklist
+
+| Question                                                 | If yes                                 | If no                                         |
+| -------------------------------------------------------- | -------------------------------------- | --------------------------------------------- |
+| Are your consumers machines or backend services?         | API keys are a strong fit              | Consider OAuth for human users                |
+| Do you need delegated user consent ("act on behalf of")? | Use OAuth                              | API keys work well                            |
+| Do consumers need to refresh credentials periodically?   | OAuth handles this with refresh tokens | API keys are simpler - no refresh flow needed |
+
+## Why API keys over JWTs for public APIs
+
+Developers sometimes default to JWTs for everything because they are a
+"standard." But for public and partner APIs, API keys have concrete advantages:
+
+### Simpler developer experience
+
+An API key is a single string. Your consumer puts it in a header and makes a
+request:
+
+```bash
+curl https://api.example.com/v1/orders \
+  -H "Authorization: Bearer zpka_d67b7e241bb948758f415b79..."
+```
+
+No token endpoint, no client credentials, no refresh flow, no clock skew issues.
+The time from "I got my API key" to "I made my first successful request" is
+measured in seconds.
+
+### Opaque by design
+
+A JWT is a base64url-encoded JSON object. Anyone can decode it and see the
+claims inside - user IDs, email addresses, roles, org names. This is a feature
+when you need claims on the client side, but it is a liability when you are
+issuing credentials to third parties. Leaking a JWT leaks its contents.
+
+API keys are opaque strings. They contain no embedded data. The consumer's
+identity and metadata are stored server-side and resolved at validation time.
+Nothing is leaked if the key is intercepted, beyond the key itself.
+
+### Instant revocation
+
+When you revoke a JWT, it remains valid until it expires. The only way to
+force-invalidate a JWT before expiry is to maintain a server-side blocklist -
+which eliminates the main advantage of JWTs (stateless validation).
+
+When you delete or expire an API key in Zuplo, the change propagates globally in
+seconds. A revoked key stops working as soon as edge caches refresh - within the
+configured `cacheTtlSeconds` (default 60 seconds). Compare this to a JWT with a
+15-minute or 1-hour expiry: there is no equivalent long expiry window to wait
+out.
+
+### Per-consumer identity without token management
+
+With API keys, the identity is the key itself. Zuplo resolves the consumer on
+every request and populates `request.user` with the consumer's name and
+metadata. There is no token to decode, validate, or refresh.
+
+This makes downstream logic simpler - your handlers and policies always have a
+consistent `request.user.sub` and `request.user.data` regardless of which API
+key the consumer used.
+
+Once you decide that API keys are the right fit, the next question is how keys
+are stored and surfaced to consumers.
+
+## Retrievable vs irretrievable keys
+
+One architectural decision in API key systems is whether keys are
+**retrievable** (the consumer can view the key again after creation) or
+**irretrievable** (the key is shown once at creation time and then stored as a
+hash).
+
+|                    | Retrievable                                            | Irretrievable                                            |
+| ------------------ | ------------------------------------------------------ | -------------------------------------------------------- |
+| **Examples**       | Twilio, Airtable                                       | Stripe, AWS                                              |
+| **After creation** | Consumer can view the key again in the portal          | Key is shown once - consumer must copy it immediately    |
+| **Storage**        | Key can be returned to authorized users                | Only a hash is stored - original key cannot be recovered |
+| **Trade-off**      | More convenient; reduces support burden from lost keys | Forces immediate key storage discipline                  |
+
+The conventional wisdom is that irretrievable keys are more secure because they
+are never stored in plaintext. But this has a counterintuitive downside:
+**irretrievable keys force consumers to copy the key somewhere else** - often a
+password manager, a `.env` file, a Slack message, or a sticky note. The key
+still exists in plaintext, just in a location you don't control.
+
+Retrievable keys let consumers go back to the portal when they need the key
+again, reducing the pressure to store it in an insecure location. For teams with
+less rigorous secret management practices, this can actually be the safer
+option.
+
+**Zuplo keys are retrievable.** Consumers can view their keys in the developer
+portal or through the API using the `key-format=visible` parameter. This
+balances security with the reality of how most development teams actually manage
+secrets.
+
+## They are not mutually exclusive
+
+Many APIs use both. A common pattern:
+
+- **API keys** for system-level access - your customers' backends call your API
+  with an API key that identifies their organization
+- **OAuth** for user-level access - end-users authorize a third-party app to act
+  on their behalf through your API
+
+Zuplo supports both patterns. You can apply
+[API Key Authentication](../policies/api-key-inbound.mdx) and
+[JWT Authentication](../policies/open-id-jwt-auth-inbound.mdx) to different
+routes in the same project, or even
+[combine multiple auth methods](./multiple-auth-policies.mdx) on a single route.
+
+## Next steps
+
+- [API Keys Overview](./api-key-management.mdx) - set up API key authentication
+  in minutes
+- [API Key Best Practices](./api-key-best-practices.mdx) - the 8 practices that
+  define a well-designed API key system
+- [API Key Authentication policy](../policies/api-key-inbound.mdx) - configure
+  the policy on your routes
+- [Authentication concepts](../concepts/authentication.mdx) - how all
+  authentication methods work in Zuplo

package/docs/cli/info.mdx

@@ -0,0 +1,37 @@
+---
+title: "Zuplo CLI: Info"
+sidebar_label: info
+---
+
+<CliCommand
+  command="info"
+  description="Alias for `project info`"
+  options={[
+  {
+    "name": "dir",
+    "type": "string",
+    "description": "The directory containing your Zuplo API",
+    "default": ".",
+    "required": false,
+    "deprecated": false,
+    "hidden": true,
+    "normalize": true
+  }
+]}
+  examples={[
+  [
+    "$0 info",
+    "Display information about the current linked project"
+  ]
+]}
+  usage="$0 info [options]"
+>
+
+</CliCommand>
+
+## Global options
+
+The following global options are available for all commands:
+
+- [`--help`](./global-options.mdx#help)
+- [`--api-key`](./global-options.mdx#api-key)

package/docs/cli/project-info.mdx

@@ -0,0 +1,37 @@
+---
+title: "Zuplo CLI: Project Info"
+sidebar_label: project info
+---
+
+<CliCommand
+  command="project info"
+  description="Displays information about the current project and linked environment"
+  options={[
+  {
+    "name": "dir",
+    "type": "string",
+    "description": "The directory containing your Zuplo API",
+    "default": ".",
+    "required": false,
+    "deprecated": false,
+    "hidden": true,
+    "normalize": true
+  }
+]}
+  examples={[
+  [
+    "$0 project info",
+    "Display information about the current linked project"
+  ]
+]}
+  usage="$0 project info [options]"
+>
+
+</CliCommand>
+
+## Global options
+
+The following global options are available for all commands:
+
+- [`--help`](./global-options.mdx#help)
+- [`--api-key`](./global-options.mdx#api-key)

package/docs/concepts/api-keys.md

@@ -21,15 +21,25 @@ The API key system has three core objects:
   metadata.
 
 See [API Key Management](../articles/api-key-management.mdx) for a full
-overview, and [API Key Administration](../articles/api-key-administration.mdx)
-for managing consumers in the portal.
+overview, and
+[Manage Keys in the Portal](../articles/api-key-administration.mdx) for managing
+consumers in the portal.
 
 ## How validation works
 
 When a request includes an API key, the
 [API Key Authentication](../policies/api-key-inbound.mdx) policy validates it
-against Zuplo's globally distributed key service. Validation happens at the edge
-in 300+ data centers, keeping latency low and load off your backend.
+through a multi-step process at the edge in 300+ data centers:
+
+1. **Format check** - the key is checked for the correct `zpka_` prefix and
+   structure. Malformed keys are rejected immediately without any network call.
+2. **Checksum validation** - the key's built-in checksum signature is verified.
+   This catches typos and garbage keys in microseconds.
+3. **Cache lookup** - the edge checks its local cache for this key. If the key
+   was recently validated (or recently rejected), the cached result is used.
+4. **Key service lookup** - if the key is not cached, Zuplo's globally
+   distributed key service is queried. The result is then cached for the
+   configured TTL (default 60 seconds).
 
 Key changes (creation, revocation, deletion) replicate globally in seconds.
 
@@ -42,6 +52,16 @@ This lets downstream policies and handlers make authorization decisions, apply
 per-consumer [rate limits](./rate-limiting.md), or forward identity to your
 backend.
 
+:::note
+
+The `cacheTtlSeconds` option on the API Key Authentication policy controls how
+long validation results are cached at each edge location. Higher values reduce
+latency but delay the effect of key revocation. A revoked key could still be
+accepted for up to `cacheTtlSeconds` after revocation. The default of 60 seconds
+is a good balance for most use cases.
+
+:::
+
 See [Authentication](./authentication.mdx) for how `request.user` works across
 all auth methods, and [RequestUser](../programmable-api/request-user.mdx) for
 the full type reference.
@@ -74,7 +94,7 @@ organizing consumers via the API). Tags are not sent to the runtime.
 API keys are the right authentication method when you need to identify an
 organization, system, or service calling your API. Companies like Stripe,
 Twilio, and SendGrid use API keys because they offer a simple developer
-experience — a single string in a header, easy to test with curl, and no token
+experience - a single string in a header, easy to test with curl, and no token
 refresh flow.
 
 Use API keys when:
@@ -94,6 +114,10 @@ Use OAuth or JWT when:
 API keys and JWT/OAuth are not mutually exclusive. Many APIs use API keys for
 system-level access and OAuth for user-level actions.
 
+For a full comparison including a decision checklist and retrievable vs
+irretrievable keys, see
+[When to Use API Keys](../articles/when-to-use-api-keys.md).
+
 ## API key format
 
 Zuplo API keys use a structured three-part format:
@@ -104,21 +128,21 @@ zpka_<random>_<checksum>
 
 Each part serves a specific purpose:
 
-- **`zpka_` prefix** — identifies the string as a Zuplo API key. This enables
+- **`zpka_` prefix** - identifies the string as a Zuplo API key. This enables
   automated [leak detection](../articles/api-key-leak-detection.mdx) via GitHub
   secret scanning (scanners match the prefix pattern), helps support teams
   identify key types during debugging, and distinguishes Zuplo keys from other
   credentials in logs and config files.
-- **Random body** — a cryptographically random string that serves as the actual
+- **Random body** - a cryptographically random string that serves as the actual
   credential. This portion is generated using a secure random source and
   provides the entropy that makes each key unique.
-- **Checksum signature** — a suffix that allows instant format validation. When
+- **Checksum signature** - a suffix that allows instant format validation. When
   a request arrives, Zuplo can verify the checksum mathematically in
   microseconds to confirm the key is structurally valid before making any
   network call. This rejects typos, truncated keys, and garbage strings without
   touching the database.
 
-The underscore separators are also intentional — they ensure that a double-click
+The underscore separators are also intentional - they ensure that a double-click
 on the key in most text editors and terminals selects the entire string,
 reducing the chance of accidentally copying a partial key.
 
@@ -155,9 +179,6 @@ when a user signs in using
 [Auth0](../dev-portal/dev-portal-create-consumer-on-auth.mdx) or another
 identity provider.
 
-You can also embed the key management UI directly in your own application using
-the [API Key React Component](../articles/api-key-react-component.mdx).
-
 ## Buckets and environments
 
 Each project has separate buckets for production, preview, and working copy
@@ -187,20 +208,19 @@ See the [API Reference](/docs/api) for the complete endpoint documentation.
 
 ## Related documentation
 
-- [API Key Management](../articles/api-key-management.mdx) -- Overview and
+- [API Keys Overview](../articles/api-key-management.mdx) -- Overview and
   getting started
 - [API Key Authentication Policy](../policies/api-key-inbound.mdx) -- Policy
   configuration reference
-- [API Key Administration](../articles/api-key-administration.mdx) -- Managing
-  keys in the portal
-- [Using the API Key API](../articles/api-key-api.mdx) -- Programmatic
+- [Manage Keys in the Portal](../articles/api-key-administration.mdx) --
+  Managing keys in the portal
+- [Use the Developer API](../articles/api-key-api.mdx) -- Programmatic
   management
-- [End User Access](../articles/api-key-end-users.mdx) -- Self-serve in the
-  developer portal
-- [React Component](../articles/api-key-react-component.mdx) -- Embed key
-  management in your app
-- [Leak Detection](../articles/api-key-leak-detection.mdx) -- GitHub secret
-  scanning
-- [Buckets](../articles/api-key-buckets.mdx) -- Bucket configuration
-- [Service Limits](../articles/api-key-service-limits.mdx) -- Rate limits and
-  quotas
+- [Share Keys with End Users](../articles/api-key-end-users.mdx) -- Self-serve
+  in the developer portal
+- [API Key Leak Detection](../articles/api-key-leak-detection.mdx) -- GitHub
+  secret scanning
+- [Buckets and Environments](../articles/api-key-buckets.mdx) -- Bucket
+  configuration
+- [API Key Service Limits](../articles/api-key-service-limits.mdx) -- Rate
+  limits and quotas

package/docs/errors/unauthorized.mdx

@@ -46,5 +46,5 @@ configuration details.
 
 ## Related resources
 
-- [API Key Authentication](../articles/api-key-authentication.mdx)
-- [API Key Administration](../articles/api-key-administration.mdx)
+- [Authentication and Authorization](../articles/api-key-authentication.mdx)
+- [Manage Keys in the Portal](../articles/api-key-administration.mdx)

package/docs/policies/monetization-inbound/schema.json

@@ -4,7 +4,7 @@
   "type": "object",
   "title": "Monetization",
   "isDeprecated": false,
-  "isPaidAddOn": true,
+  "isPaidAddOn": false,
   "isEnterprise": false,
   "isInternal": false,
   "isBeta": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.69.4",
+  "version": "6.69.5",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.69.4",
-    "@zuplo/core": "6.69.4",
-    "@zuplo/runtime": "6.69.4",
+    "@zuplo/cli": "6.69.5",
+    "@zuplo/core": "6.69.5",
+    "@zuplo/runtime": "6.69.5",
     "@zuplo/test": "1.4.0"
   }
 }