Zuplo
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.

In order to obtain an API Key for the Developer API, go to your account settings in the Zuplo Portal. More information

​Models

The service contains three primary object: Buckets, Consumers, and API Keys. For an 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.

In most cases, you wont manage API Keys directly. When using the API, it 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.

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

# Your Zuplo Account Name
export ACCOUNT_NAME=my-account
# Your bucket API URL (Found in Settings > Project Information)
export BUCKET_NAME=my-bucket
# Your Zuplo API Key (Found in Settings > Zuplo API Keys)
export ZAPI_KEY=zpka_YOUR_API_KEY
bash

​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 is 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.

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
shell

The response will look like this:

{
  "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"
    }
  ]
}
json

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

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"
shell

The response will look like this:

{
  "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
}
json

​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.

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.

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

​Reference

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

End User AccessReact Component