Start

API key authentication

Authenticate documented inquiry operations with X-Api-Key.

All endpoints documented in this guide authenticate with an API key sent in the X-Api-Key request header.

API key header

Keys contain the zk_live_ prefix followed by a 32-character Base64URL value. The plaintext key is shown once when created. Send it only from trusted backend infrastructure.

Header

http

X-Api-Key: zk_live_<32-character-Base64URL-secret>

Merchant key errors

Name	Type	Description
`API_KEY_INVALID`	401	Missing, malformed, or unmatched key.
`API_KEY_REVOKED`	401	Key revoked or revokedAt set.
`API_KEY_EXPIRED`	401	expiresAt is in the past.

Correlation IDs

Send an optional X-Correlation-Id to connect your logs with Zippy request logs. If omitted, Zippy generates a UUID. The effective correlation ID is returned in the response header and included in Problem Details responses.

Optional request header

http

X-Correlation-Id: merchant-request-123

Rate limits

The current default is 120 requests per 60 seconds for each API key and endpoint scope. Exceeding the limit returns 429 Too Many Requests.

Problem Details

Errors use application/problem+json. Branch on the stable code field and retain correlationId when contacting support.

Problem Details response

json

{
  "type": "{problem-type-base-url}/errors/API_KEY_INVALID",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key is missing or invalid",
  "instance": "/api/v1/customer/inquiries",
  "code": "API_KEY_INVALID",
  "correlationId": "c7ccb49d-e6bb-45f7-b834-93c4521a6857"
}

Error fields

Name	Type	Description
`type`	URI	Environment-specific URI identifying the problem category.
`title`	string	Short HTTP error summary.
`status`	integer	HTTP status code.
`detail`	string	Human-readable explanation for this occurrence.
`instance`	string	Request path associated with the failure.
`code`	string	Stable application error code.
`correlationId`	string	Identifier used to trace the request.

API key lifecycle

Schema statuses: ACTIVE, ROTATING, REVOKED, EXPIRED. Auth lookup currently matches ACTIVE keys by prefix, then validates revoke/expiry.

Security practices

Store keys in a secrets manager or encrypted environment configuration.
Send requests only over HTTPS.
Do not commit, log, or place keys in client-side applications.
Use a separate key per environment and revoke keys that may be compromised.

Common failures

Sending the key under a header other than X-Api-Key.
Reusing a revoked key after dashboard delete/revoke.
Calling an endpoint that is not part of the documented API-key surface.

Getting started

Core concepts