Copy page

API Keys

Buckets and Environments

Applies to

Gatewayruntime for API, AI, and MCP gateways

Hosting

Managed EdgeManaged DedicatedSelf-Hosted

API keys are stored in "buckets," which organize and isolate authentication credentials across different environments. Learn more in the API Key API documentation.

Default bucket configuration

Zuplo automatically creates three buckets for each project:

• Production: Stores API keys for the production environment (your default Git branch)
• Preview: Stores API keys shared across all preview environments (non-default Git branches)
• Development: Stores API keys for the development (working copy) environment

For more information on how environments relate to Git branches, see Branch-Based Deployments.

Bucket identifiers

Every bucket has an ID that starts with bckt_, and a name. Use the bucket ID whenever you identify a bucket, both in the Zuplo Developer API and in policy configuration. To copy it, open Services → API Keys → Consumers in the Zuplo Portal and select the environment with the Dev / Preview / Prod switcher. The Bucket ID pill sits beside the environment badge under the API Key Service heading, with a copy button.

Custom bucket configuration

To use a custom bucket, specify its bucketId in your API Key policy options:

Code
{
  "export": "ApiKeyInboundPolicy",
  "module": "$import(@zuplo/runtime)",
  "options": {
    "bucketId": "bckt_2HaK3odRyJle6NJSu8mzNKBC30BYxllxL",
    "allowUnauthenticatedRequests": false
  }
}

For more information about finding a bucket ID, see Bucket identifiers.

When the configuration sets no bucket, the policy uses the default bucket for the current environment.

Creating custom buckets

Create custom buckets using the API Key management API. See the create buckets endpoint for details.

The following example creates a bucket for a QA environment. The response includes the new bucket's id, which is the value to set as bucketId on the policy:

Code
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"}'