Skip to main content

API Key Management

Zuplo allows developers to add API key authentication to their API in only a few minutes. With Zuplo's API Key Management you can either issue tokens to your customers or enable the developer portal to allow self-serve API Keys based on custom permissions and settings.

tip

For a complete tutorial on adding API Key authentication and management see the quickstart.

API Key Consumers​

API Key Consumers are entities that can consume your API - typically people, customers, partners or services. API Key consumers are managed by API Key Managers. API Key Managers are people authorized to issue and manage API Keys for the API Key Consumer. Adding managers to the API Key Consumer is done by setting email addresses for each user.

Each API Key Manager who logs into the Developer Portal can issue or manage API Keys. Note that every manager on a consumer has access to all the SAME API keys for that consumer. If you would like each user of your API to have their own API Keys, make each user their own API Key Consumer with a single manager.

API Key Consumer Metadata​

Metadata of the API Key Consumer can be any JSON object. This metadata is what gets passed to each request in your API Gateway as the request.user.

For example, an API Key Consumer with the sub set to big-co and the following metadata:

{
  "companyId": 123,
  "plan": "gold"
}

would return a request.user object to your route if the API Key is successfully authenticated.

async function (request: ZuploRequest, context: ZuploContext) {
  return context.user;
  // returns the following
  // {
  //   "sub": "big-co",
  //   "data": {
  //     "companyId": 123,
  //     "plan": "gold"
  //   }
  // }
}

Manage API Key Consumers​

API Key Consumers can be managed in the API Key Consumers section under the Settings tab.

API Key Consumers

To add a new API Key Consumer click the Add new consumer button and complete the form.

New API Key Consumer

API Key Authentication & Authorization​

Each route in your API that you want to be secured with API Key Authentication must be configured with the API Key Authentication Policy. This policy ensures that callers to the route have a valid API key and authenticates the user of the request.

The API Key Consumer's metadata and sub are set as the request.user object on each request that is authenticated with the API Key Authentication policy. This data can be used to perform authorization, routing, etc. for each request.

For example, features can be gated based on a plan value in the metadata.

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.

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 and policies

API Keys in the Developer Portal​

When API Key Managers log into the Developer Portal they can copy, manage, or create new API Keys.

API Keys in Developer Portal