Copy page

API Keys

Using the API Key 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 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.

Models

The service contains three primary object: Buckets, Consumers, and API Keys. For a conceptual overview of these objects see 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.

Usage

This section explains common scenarios for managing API keys using the API. For other uses, see the full Developer API reference.

All examples assume two environment variables are set (in your terminal, not inside Zuplo)

Code
# 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.

Code
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:

Code
{
  "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 policy.

Query Consumers with API Keys By Tags

Code
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:

Code
{
  "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

Key rotation is a critical part of API key lifecycle management. Instant revocation of a key can break every system that depends on it, so Zuplo supports rolling transitions — creating a new key while keeping the old key active for a defined grace period.

When you call the roll key endpoint, Zuplo:

1. Creates a new key with no expiration for the consumer
2. Sets the expiresOn date on all existing keys to the value you specify

This gives consumers time to update their integration to the new key before the old one stops working.

Choosing a transition period

The right expiresOn value depends on how quickly consumers can update their keys:

• Leaked key response — set expiresOn to a past date or within minutes. Security incidents demand immediate action; a brief disruption is preferable to continued exposure.
• Routine rotation — 24 to 72 hours gives most teams enough time to propagate the new key through CI/CD pipelines, environment variables, and secret managers.
• Scheduled rotation — for large organizations, 7 to 14 days accommodates deploy freezes, multi-team coordination, and staged rollouts.

The following call sets all existing keys to expire on the specified date and creates a new key without an expiration.

Code
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" \
  --header "Content-Type: application/json" \
  --data '{"expiresOn":"2026-04-19T00:00:00.000Z"}'

Reference

The full API Reference for the API Service is hosted using a Zuplo developer portal at https://dev.zuplo.com/docs/.