Copy page

API Keys

API Keys Overview

Zuplo provides a fully managed API key authentication system that you can add to your API in minutes. Every key is validated at the edge across 300+ data centers, so authentication is fast for your consumers and offloads work from your backend.

Why API keys?

API keys are the standard authentication method for API-first companies like Stripe, Twilio, and SendGrid. They are the right choice when you need to authenticate an organization, system, or service rather than an individual user acting on their own behalf (which is where OAuth excels).

Compared to JWT-based auth, API keys offer simpler developer experience — a single string in a header, easy to test with curl, and no token refresh flow. API keys are opaque, meaning they don't leak claim structure the way a decoded JWT does. And because each key maps to a consumer identity in Zuplo, you can revoke access instantly — you don't need to wait for a token to expire.

For a deeper comparison, see the Zuplo blog post on API key authentication best practices.

What you get with Zuplo API keys

• Thoughtful key format — keys use a zpka_ prefix, cryptographically random body, and checksum signature. The prefix enables GitHub secret scanning, the checksum allows instant format validation without a database call, and the underscore formatting means a double-click selects the entire key. See API key format for the full breakdown.
• Leak detection — Zuplo is a GitHub secret scanning partner. If a key is committed to any GitHub repository, you are notified immediately.
• Self-serve key management — give your API consumers a developer portal where they can create, view, roll, and revoke their own keys.
• Edge validation — keys are validated at the edge, keeping latency low and your backend protected. See how validation works for details on caching and replication.
• Key rotation with transition periods — the roll-key API creates a new key and sets an expiration on existing keys, so consumers have time to migrate without downtime.

Fully managed global infrastructure

Zuplo builds and manages the API key infrastructure so you don't have to. The service handles key storage, global replication, edge caching, and validation at scale — supporting millions of keys and virtually unlimited throughput.

Keys replicate around the world in seconds. When a key is created, revoked, or deleted, the change propagates to all 300+ edge locations within seconds, ensuring your API is never open to unauthorized access for longer than the configured cache TTL.

How authentication works

When a request arrives at Zuplo with an API key, the API Key Authentication policy validates it through a multi-step process:

1. Format check — the key is checked for the correct zpka_ prefix and structure. Malformed keys are rejected immediately without any network call.
2. Checksum validation — the key's built-in checksum signature is verified. This catches typos and garbage keys in microseconds.
3. Cache lookup — the edge checks its local cache for this key. If the key was recently validated (or recently rejected), the cached result is used.
4. Key service lookup — if the key isn't cached, Zuplo's globally distributed key service is queried. The result is then cached for the configured TTL (default 60 seconds).

After successful validation, request.user is populated with the consumer's identity and metadata, which downstream policies and handlers can use for authorization, rate limiting, and routing. See how validation works for more details.

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

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

Code
customer=1234

You can see more on how to use tags in the document on managing consumers and keys using the API

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 use a structured format: a zpka_ prefix, a cryptographically random body, and a checksum signature. This format enables leak detection via GitHub secret scanning and allows instant format validation without a database call. Zuplo's API Key management service also supports custom key formats (enterprise plan required), though custom formats lose leak detection support.