zuplo 6.67.32 → 6.68.0

package/docs/articles/api-key-api.mdx

@@ -0,0 +1,220 @@
+---
+title: Using the API Key API
+sidebar_label: Using the API
+---
+
+Zuplo runs a globally distributed API Key management service that scales to
+handle billions of daily key validation requests while maintaining low latency
+from any region around the world.
+
+Management of API Keys and consumers
+[can be performed in the Zuplo Portal](./api-key-management.mdx) and for
+end-users in the Zuplo Developer Portal. However, all management operations
+regarding API Keys can also be performed using the
+[Zuplo Developer API](https://zuplo.com/docs/api/api-keys-keys).
+
+:::info
+
+In order to obtain an API Key for the Developer API, go to your account settings
+in the Zuplo Portal. [More information](./accounts/zuplo-api-keys)
+
+:::
+
+## Models
+
+The service contains three primary object: **Buckets**, **Consumers**, and **API
+Keys**. For a conceptual overview of these objects see
+[Key Concepts](./api-key-management#key-concepts). Below is an ER diagram
+showing the relationships of the three primary objects and their most important
+fields.
+
+The Consumer is the most important object. Each consumer is in a bucket.
+Consumers can contain one or more API Keys.
+
+### Buckets
+
+Buckets are the top level group for this service. A bucket could be used with a
+single Zuplo environment or shared among multiple environments or projects. By
+default a Zuplo API Gateway project will be created with several buckets that
+map to production, preview, and development (working copy) environments.
+
+Enterprise plan customers run complex configurations where buckets are shared
+across gateway projects or even accounts. This can allow your end-users to
+authenticate to all your APIs with a single API key with unified permissions.
+
+### Consumers
+
+Consumers are the core of the API Key service. The consumer is the "identity" of
+any API Keys that are created. Consumers have a `name` which must be unique in
+the bucket. This `name` is used as the default `user.sub` property in the API
+Key Authentication policy.
+
+### API Keys
+
+A Consumer can have any number of API keys associated with it. Each API Key
+shares the same identity (for example Consumer) when authenticating with this
+service. Expired keys won't be permitted to authenticate after their expiration.
+
+:::tip
+
+In most cases, you won't manage API Keys directly. When using the API, the
+typical configuration is to create a consumer with an API key and each consumer
+has only a single API key except when performing operations like rolling keys.
+
+:::
+
+## Usage
+
+This section explains common scenarios for managing API keys using the API. For
+other uses, see the full [Developer API reference](https://dev.zuplo.com).
+
+All examples assume two environment variables are set (in your terminal, not
+inside Zuplo)
+
+```bash
+# Your Zuplo Account Name
+export ACCOUNT_NAME=my-account
+# Your bucket API URL (Found in Settings > General)
+export BUCKET_NAME=my-bucket
+# Your Zuplo API Key (Found in Settings > Zuplo API Keys)
+export ZAPI_KEY=zpka_YOUR_API_KEY
+```
+
+### Creating a Consumer with a Key
+
+When creating a new Consumer, it's a good idea to include some useful metadata
+like the `organizationId` or a particular `plan` that's associated with that
+user.
+
+Tags are used for querying the consumers later. It's often useful to store some
+external identifier that links this consumer to your internal data as a tag.
+
+```shell
+curl \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers?with-api-key=true \
+  --request POST \
+  --header "Content-type: application/json" \
+  --header "Authorization: Bearer $API_KEY" \
+  --data @- << EOF
+{
+  "name": "my-consumer",
+  "description": "My Consumer",
+  "metadata": {
+    "orgId": 1234,
+    "plan": "gold"
+  },
+  "tags": {
+    "externalId": "acct_12345"
+  }
+}
+EOF
+```
+
+The response will look like this:
+
+```json
+{
+  "id": "csmr_sikZcE754kJu17X8yahPFO8J",
+  "name": "my-consumer",
+  "description": "My Consumer",
+  "createdOn": "2023-02-03T21:33:17.067Z",
+  "updatedOn": "2023-02-03T21:33:17.067Z",
+  "tags": {
+    "externalId": "acct_12345"
+  },
+  "metadata": {
+    "orgId": 1234,
+    "plan": "gold"
+  },
+  "apiKeys": [
+    {
+      "id": "key_AM7eAiR0BiaXTam951XmC9kK",
+      "createdOn": "2023-06-19T17:32:17.737Z",
+      "updatedOn": "2023-06-19T17:32:17.737Z",
+      "expiresOn": null,
+      "key": "zpka_d67b7e241bb948758f415b79aa8exxxx_2efbxxxx"
+    }
+  ]
+}
+```
+
+You can use this API Key to call your Zuplo API Gateway that's protected by the
+[API Key Authentication](/docs/policies/api-key-inbound) policy.
+
+### Query Consumers with API Keys By Tags
+
+```shell
+export ORG_ID=1234
+curl \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers/?include-api-keys=true&key-format=visible&tag.orgId=$ORG_ID \
+  --header "Authorization: Bearer $API_KEY"
+```
+
+The response will look like this:
+
+```json
+{
+  "data": [
+    {
+      "id": "csmr_sikZcE754kJu17X8yahPFO8J",
+      "name": "my-consumer",
+      "description": "My Consumer",
+      "createdOn": "2023-02-03T21:33:17.067Z",
+      "updatedOn": "2023-02-03T21:33:17.067Z",
+      "tags": {
+        "externalId": "acct_12345"
+      },
+      "metadata": {
+        "orgId": 1234,
+        "plan": "gold"
+      },
+      "apiKeys": [
+        {
+          "id": "key_AM7eAiR0BiaXTam951XmC9kK",
+          "createdOn": "2023-06-19T17:32:17.737Z",
+          "updatedOn": "2023-06-19T17:32:17.737Z",
+          "expiresOn": null,
+          "key": "zpka_d67b7e241bb948758f415b79aa8exxxx_2efbxxxx"
+        }
+      ]
+    }
+  ],
+  "offset": 0,
+  "limit": 1000
+}
+```
+
+### Roll a Consumer's Keys
+
+Sometimes you will want to create a new key and expire the current keys. Instead
+of calling the API for each key and manually creating a new key, you can simply
+call the roll key endpoint.
+
+:::tip{title="Tags for Request Authorization"}
+
+One useful feature of the API Key service is that most requests can have `tags`
+added to the query parameter even if they aren't get requests. This is useful
+when you want to call the API and ensure some basic condition is met without
+having to first do a GET to retrieve data on the object. For example, in the
+roll key request below the `orgId` tag is set on the request - this ensures that
+the consumer being updated is tagged with that org.
+
+:::
+
+The following call with set all existing keys to have the expiration date set in
+the request body and will create a new key without an expiration.
+
+```shell
+export ORG_ID=1234
+export CONSUMER_NAME=my-consumer
+curl \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers/$CONSUMER_NAME/roll-key?tag.orgId=$ORG_ID \
+  --request POST \
+  --header "Authorization: Bearer $API_KEY"
+  --data '{"expiresOn":"2023-04-18"}'
+```
+
+## Reference
+
+The full API Reference for the API Service is hosted using a Zuplo developer
+portal at [https://dev.zuplo.com/docs/](https://dev.zuplo.com/docs/).

package/docs/articles/api-key-authentication.mdx

@@ -0,0 +1,195 @@
+---
+title: API Key Authentication & Authorization
+sidebar_label: Authentication
+---
+
+With the [API Key Authentication Policy](../policies/api-key-inbound.mdx)
+configured on your API routes you can build additional policies that run after
+the API Key Authentication policy to perform additional checks or authorization
+on the consumer.
+
+## Request User Object
+
+After each successful authentication the policy will set the `request.user`
+object. The name of the API Key consumer is set to the `request.user.sub`
+property. Any `metadata` attached to the consumer is set to the
+`request.user.data` property. The interface of `request.user` is shown below.
+
+```ts
+/**
+ * The User object set by the API Key Authentication policy
+ */
+interface User {
+  /**
+   * The name of the API Key consumer
+   */
+  sub: string;
+  /**
+   * The metadata attached to the API Key consumer
+   */
+  data: any;
+}
+```
+
+So if you created a consumer with the following configuration:
+
+```json
+{
+  "name": "my-consumer",
+  "metadata": {
+    "companyId": 12345,
+    "plan": "gold"
+  }
+}
+```
+
+The request object would be the following:
+
+```ts
+context.log.debug(request.user);
+// Outputs:
+// {
+//   sub: "my-consumer",
+//   data: {
+//     companyId: 12345,
+//     plan: "gold"
+//   }
+// }
+```
+
+:::note
+
+One question you might have is why is the `request.user` object not the same
+shape as the API Key Consumer object. for example why doesn't it has
+`request.user.name` and `request.user.metadata` properties.
+
+The reason is because the `request.user` object is reused by many different
+kinds of authentication policies and they all conform to the same interface with
+`sub` and `data`.
+
+:::
+
+## Using Consumer Data in Code
+
+It's possible to write additional policies that run after the API Key
+Authentication policy that perform further gating or authorization of the
+request based on the data set in the consumer.
+
+For example, you could gate access to a feature by checking for the `plan` value
+stored in metadata (exposed via `request.user.data.plan`).
+
+```ts
+async function (request: ZuploRequest, context: ZuploContext) {
+  if (request.user?.data.plan !== "gold") {
+    return new Response("You need to upgrade your plan", {
+      status: 403
+    });
+  }
+  return new Response("you have the gold plan!");
+}
+```
+
+The `metadata` could also be used to route requests to dedicated customer
+services.
+
+```ts
+async function (request: ZuploRequest, context: ZuploContext) {
+  const { customerId } = request.user.data;
+  return fetch(`https://${customerId}.customers.example.com/`
+}
+```
+
+The `request.user` object can be used in both
+[handlers](../handlers/custom-handler.mdx) and
+[policies](../policies/custom-code-inbound.mdx)
+
+If you had a simple [function handler](../handlers/custom-handler.mdx) as
+follows, it would return a `request.user` object to your route if the API Key is
+successfully authenticated:
+
+```ts
+async function (request: ZuploRequest, context: ZuploContext) {
+  // auto-serialize the user object and return it as JSON
+  return request.user;
+}
+```
+
+Would send the following response.
+
+```json
+{
+  "sub": "my-consumer",
+  "data": {
+    "companyId": 12345,
+    "plan": "gold"
+  }
+}
+```
+
+## Testing API Key Authentication
+
+When running tests there are several ways to handle API Key authentication. The
+following strategies cover testing with API Key authentication both locally and
+in deployed environments.
+
+### Testing locally
+
+When running API Key Authentication locally, if you
+[link the project](../cli/link.mdx) to a project, the same API Key bucket is
+shared by both your development (working copy) environment and local
+development.
+
+### Setting the API Key bucket name
+
+Either locally or in CI/CD you can specify any API Key bucket on the
+[API Key Authentication](../policies/api-key-inbound.mdx) policy by setting the
+`bucketName` property. This allows using a consistent API Key bucket that is set
+up with consumers as required for testing. You can use the
+[Zuplo Developer API](https://dev.zuplo.com) to
+[create and manage buckets](./api-key-management.mdx), consumers, keys, and
+more.
+
+### Selectively disabling
+
+:::danger
+
+Be extremely careful using this strategy. If configured incorrectly this could
+leave your API open to unauthorized access.
+
+:::
+
+Another option is to disable authentication on endpoints for testing purposes.
+One way of doing this is to configure the
+[API Key Authentication](../policies/api-key-inbound.mdx) policy to allow
+unauthenticated requests through. This can be done by setting
+`allowUnauthenticatedRequests` to true.
+
+In order to enforce authentication with this setting disabled, you can create a
+policy that comes after that selectively enforces auth based on some condition.
+
+For example, an environment variable flag could be used to disable auth with the
+following policy.
+
+```ts
+import {
+  ZuploContext,
+  ZuploRequest,
+  environment,
+  HttpProblems,
+} from "@zuplo/runtime";
+
+export default async function enforceAuth(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  if (environment.DISABLE_AUTH === "AUTH_DISABLED") {
+    return request;
+  }
+
+  if (!request.user) {
+    return HttpProblems.unauthorized(request, context);
+  }
+
+  return request;
+}
+```

package/docs/articles/api-key-buckets.mdx

@@ -0,0 +1,61 @@
+---
+title: Buckets and Environments
+---
+
+API keys are stored in "buckets," which organize and isolate authentication
+credentials across different environments. Learn more in the
+[API Key API documentation](https://dev.zuplo.com/docs).
+
+## Default bucket configuration
+
+Zuplo automatically creates three buckets for each project:
+
+- **Working copy**: Stores API keys for the working-copy environment
+- **Production**: Stores API keys for the production environment (your default
+  Git branch)
+- **Shared**: Stores API keys shared across all other environments
+
+For more information on how environments relate to Git branches, see
+[Branch-Based Deployments](./branch-based-deployments.mdx).
+
+## Custom bucket configuration
+
+To use a custom bucket, specify the `bucketName` in your API Key policy options:
+
+```json
+{
+  "export": "ApiKeyInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "bucketName": "contoso-qa-env",
+    "allowUnauthenticatedRequests": false
+  }
+}
+```
+
+When no `bucketName` appears in the configuration, the policy uses the default
+bucket for the current environment.
+
+## Creating custom buckets
+
+Create custom buckets using the
+[API Key management API](https://dev.zuplo.com/docs). See the
+[create buckets endpoint](https://dev.zuplo.com/docs/routes#apikeybucketsservice_create)
+for details.
+
+The following example creates a bucket for a QA environment:
+
+```bash
+curl --request POST \
+  --url https://dev.zuplo.com/v1/accounts/YOUR_ACCOUNT_NAME/key-buckets \
+  --header 'Authorization: Bearer YOUR_ZAPI_KEY' \
+  --header 'Content-Type: application/json' \
+  --data '{"name":"contoso-qa-bucket","description":"API Key bucket for QA Environment"}'
+```
+
+:::note
+
+Replace `YOUR_ACCOUNT_NAME` with your account name and `YOUR_ZAPI_KEY` with your
+Zuplo API key.
+
+:::

package/docs/articles/api-key-end-users.mdx

@@ -0,0 +1,52 @@
+---
+title: API Key End User Access
+sidebar_label: End User Access
+---
+
+For any API Key to be useful it needs to be shared with the right end-user.
+Zuplo provides several options depending on the level of customization required.
+
+## Dev & Testing
+
+For development and testing, the easiest way to obtain an API key is right in
+the [Zuplo Management Portal](https://portal.zuplo.com). From inside the **API
+Key Consumers** section in the **Settings** tab you can create and manage
+consumers and their keys.
+
+For quick access the newest, non-expired API key is shown in this section.
+
+![API key section](../../public/media/api-key-end-users/98a3d62f-1b61-4f41-8bac-665e0b02309e.png)
+
+## Zuplo Developer Portal
+
+If you are using Zuplo's integrated developer portal to share your API with your
+end-users, you can easily enable API Key management to authenticated users of
+the portal.
+
+When API Key Managers log into the Developer Portal they can copy, manage, or
+create new API Keys.
+
+![API Keys in Developer Portal](../../public/media/api-key-dev-portal.png)
+
+## React Component and API
+
+If you would prefer to integrate API Key management inside of your own portal
+and you are building with React, Zuplo offers an
+[open source API Key Manager component](https://github.com/zuplo/api-key-manager)
+that makes it easy to allow your users self serve access to their keys.
+
+Additionally, you can use the
+[Auth Translation API](https://github.com/zuplo/sample-auth-translation-api)
+sample as a starting point for building your management API using Zuplo.
+
+You can find a demo of this component at https://api-key-manager.com.
+
+## Zuplo Developer API
+
+Finally, if you want complete control over the entire experience, you can
+utilize Zuplo's Developer API to manage the full lifecycle of API Consumers and
+Keys.
+
+For more information on using the API to manage consumers and keys, see
+[Programmatic API Key Management](./api-key-api.mdx) and the
+[Zuplo Developer API documentation](https://dev.zuplo.com).

package/docs/articles/api-key-leak-detection.mdx

@@ -0,0 +1,75 @@
+---
+title: API Key Leak Detection
+sidebar_label: Leak Detection
+---
+
+## API Key Format
+
+Zuplo uses a specially formatted API Key structure that allows us to
+[partner with GitHub's secret scanning](https://github.blog/changelog/2022-07-13-zuplo-is-now-a-github-secret-scanning-partner/)
+to protect your users from accidentally leaked keys.
+
+We think the safety of your API key consumers is paramount, so this feature is
+available to all Zuplo customers, including free.
+
+## API Key Leak Detection
+
+API keys should never be stored in source control. Accidentally committing API
+keys to source control is a common attack vector that leads to compromises of
+organizations both large and small.
+
+Zuplo participates in
+[GitHub's Secret Scanning](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning)
+program to detect if your or your customer's API Keys are checked into source
+control on GitHub.
+
+If an API Key for your Zuplo API Gateway is compromised by checking it into a
+public or private GitHub repository, Zuplo will be notified and can take action
+immediately.
+
+## Leak Notifications
+
+You will receive notifications of API Key leaks via email as well as in-app
+notifications. You can customize the notifications settings by going to your
+[Profile](https://portal.zuplo.com/user/profile) in the Zuplo Portal.
+
+:::note
+
+For security reasons we don't include the full API Key in the notifications we
+send. If you need the full API Key please contact support.
+
+:::
+
+## Recommended Actions
+
+If you receive an alert that an API Key has been leaked, we recommend taking one
+of the following actions immediately.
+
+### Notify Your Customer
+
+Notify your customer and ask them to login to your Zuplo powered developer
+portal and instruct them to roll the API Key. This way the old key is revoked
+and they get a new key.
+
+### Roll the API Key
+
+You can use the
+[Zuplo API to roll the API Key](https://dev.zuplo.com/docs/routes#roll-consumer-keys)
+for the consumer. This will create a new key and revoke the old key.
+
+```bash
+export ACCOUNT_NAME="your-account-name"
+export BUCKET_NAME="your-bucket-name"
+export CONSUMER_NAME="your-consumer-name"
+export ZUPLO_API_KEY="your-zuplo-api-key"
+
+curl --request POST \
+  --url https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers/$CONSUMER_NAME/roll-key \
+  --header 'Authorization: Bearer $ZUPLO_API_KEY' \
+  --header 'Content-Type: application/json' \
+  --data '
+{
+  "expiresOn": "2024-01-01T00:00:00.000Z"
+}
+'
+```

package/docs/articles/api-key-management.mdx

@@ -0,0 +1,100 @@
+---
+title: API Keys Overview
+sidebar_label: Overview
+---
+
+Zuplo allows developers to rapidly add API key based authentication to an API in
+minutes. There are several benefits to using Zuplo's API Key solution including
+
+- adheres to
+  [best practices of API Key implementation](https://zuplo.com/blog/2022/12/01/api-key-authentication)
+- includes [API Key Leak Detection & Notification](./api-key-leak-detection.mdx)
+- offers [out of the box and customizable solutions](./api-key-end-users.mdx)
+  for sharing API Keys
+
+:::tip
+
+To start using Zuplo API Keys in only a few minutes
+[see the quickstart](../articles/step-3-add-api-key-auth.mdx).
+
+:::
+
+## Fully Managed API Key Solution
+
+Zuplo builds and manages a global API Key solution that can handle millions (or
+billions) of API Keys and a virtually unlimited throughput to scale to the most
+demanding services.
+
+The service handles global replication of API Keys allowing your end users to be
+authenticated to your API key with minimal latency. Keys are replicated around
+the world in only a few seconds. Similarly, when keys are revoked or deleted,
+the change replicates in seconds so that your API isn't open to unauthorized
+access.
+
+## API Key Authentication at the Edge
+
+Using Zuplo's API Key Authentication policy, your API is secured from
+unauthorized access. Authorization checks happen at the edge in 300+ data
+centers around the world. This keeps load off your backend and keeps your API
+fast for your end-users.
+
+Zuplo manages all the complexity of replication, caching, and verifying your API
+keys so you don't have to.
+
+Adding API Key authentication using Zuplo takes only a few minutes.
+[See the quickstart to get started](../articles/step-3-add-api-key-auth.mdx).
+
+## Key Concepts
+
+### Consumers
+
+An API Key Consumer is the identity that can invoke your API - typically people,
+customers, partners or services. A consumer can have multiple API Keys
+associated with it - but each key authorizes the same consumer (for example
+identity)
+
+### Consumer Metadata
+
+Each consumer can be assigned metadata. This information (a
+[small JSON object](./api-key-service-limits.mdx)) is made available to the
+runtime when a user access your API using that key.
+
+For example, a Consumer might have metadata that specifies the company they're a
+member of and the plan for the account.
+
+```json
+{
+  "companyId": 123,
+  "plan": "gold"
+}
+```
+
+### Consumer Tags
+
+Consumers can also have tags associated with them. Tags are simple key value
+pairs. Tags are used for management purposes only (for example querying
+consumers through the Zuplo API). Tags don't get sent to the runtime as part of
+authorization.
+
+For example, a Consumer might be tagged in order to track the customer
+associated with the consumer.
+
+```txt
+customer=1234
+```
+
+You can see more on how to use tags in the document on
+[managing consumers and keys using the API](./api-key-api.mdx)
+
+### API Keys
+
+API Keys are the actual string value used to authenticate with an API. Unlike
+some other forms of bearer tokens, API Keys don't contain any actual data within
+the key itself.
+
+Zuplo API Keys are prefixed with the string `zpka_` followed by
+cryptographically random characters and a signature. While Zuplo's API Key
+management service supports custom key formats (enterprise plan required), the
+structured format our the key enables us to offer
+[key leak detection services](./api-key-leak-detection.mdx) to keep your API
+secure.