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

:::tip

To start using Zuplo API Keys in only a few minutes
[see the quickstart](../articles/step-3-add-api-key-auth.mdx).

:::

## 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](https://zuplo.com/blog/api-key-authentication).

## 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](./api-key-leak-detection.mdx), 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](../concepts/api-keys.md#api-key-format) for the full
  breakdown.
- **Leak detection** — Zuplo is a
  [GitHub secret scanning partner](./api-key-leak-detection.mdx). If a key is
  committed to any GitHub repository, you are notified immediately.
- **Self-serve key management** — give your API consumers a
  [developer portal](./api-key-end-users.mdx) 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](../concepts/api-keys.md#how-validation-works) for
  details on caching and replication.
- **Key rotation with transition periods** — the
  [roll-key API](./api-key-api.mdx#roll-a-consumers-keys) 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](../policies/api-key-inbound.mdx) 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](../concepts/api-keys.md#how-validation-works) for more
details.

:::note

The `cacheTtlSeconds` option on the API Key Authentication policy controls how
long validation results are cached at each edge location. Higher values reduce
latency but delay the effect of key revocation. A revoked key could still be
accepted for up to `cacheTtlSeconds` after revocation. The default of 60 seconds
is a good balance for most use cases.

:::

## 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](./api-key-service-limits.mdx)) 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.

```json
{
  "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.

```txt
customer=1234
```

You can see more on how to use tags in the document on
[managing consumers and keys using the API](./api-key-api.mdx)

### 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](./api-key-leak-detection.mdx) 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.