How to Use Harbor Gateway Cloud API

This is the v1 customer-facing API for Harbor gateway locker fleets. Use
it to create transactions, open lockers, query inventory, and manage
out-of-service state from your own backend over HTTPS.

Authentication

Every request must carry an API key in one of two headers:

X-API-Key: hgwm_<64 hex chars>

Authorization: Bearer hgwm_<64 hex chars>

Keys are issued by Luxer One operations, scoped to a single organization.
If a key leaks, revoke it immediately — a revoked key stops validating
within seconds.

Idempotency

Any mutating call can carry an Idempotency-Key header. If you retry a
request with the same key, you get the cached response from the first
attempt instead of a duplicate side effect. Strongly recommended for
locker opens, transaction creates, and anything else that could double
if it retries.

A key can only ever map to one request — mint a fresh UUIDv4 per attempt.
Replays outside the original request's response window still return the
same cached response; if you need a fresh attempt, use a new key.

Sync-feel vs. async

By default, proxy endpoints block for up to a per-endpoint default (5s
for reads, 10s for non-hardware writes, 15s for hardware ops like locker
opens). When the gateway completes in that window, you get its response
directly; when it doesn't, you get 202 Accepted with a Location
header and a pending body. Poll GET /requests/{id} until the terminal
state.

Use the Prefer header to tune the wait:

Prefer: wait=30           // block up to 30 seconds
Prefer: respond-async     // return 202 immediately, no blocking

The server clamps wait at 30 seconds.

Rate limiting

120 requests per minute per API key, default. Exceeding the limit returns
429 Too Many Requests with a Retry-After header. Every response
carries:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1713632220

Need more? Contact Luxer One operations.

HTTP status mirroring

On a terminal completed state, the HTTP status and body are the
gateway's verbatim. A 4xx from the gateway (e.g. "transaction not found")
is returned as the same 4xx from this API — you don't have to unwrap a
nested status. Non-completed terminal states (the gateway rejected,
failed to dispatch, became unresponsive) get their own status codes and
a structured error body.

Versioning

This is v1. Non-breaking additions will land under /api/customer/v1/
over time; breaking changes will appear under /v2/ with overlap and
deprecation headers (Sunset, Deprecation) on the v1 paths.

Operational response headers

Every proxy response (success or failure, after the request has been
accepted) carries:

X-Request-Id: <uuid>             # use in support tickets and log greps
X-Gateway-Id: <serial>           # the gateway that handled the request
X-Request-Duration-Ms: <int>     # how long the server held the connection

Idempotent replays additionally carry:

Idempotent-Replayed: true

Truncated responses from gateway log queries carry:

X-Response-Truncated: true

CORS

Not enabled. This API is designed for server-to-server calls; integrate
from your own backend, not directly from a browser.

How to Use Harbor Gateway Cloud API

Authentication#

Idempotency#

Sync-feel vs. async#

Rate limiting#

HTTP status mirroring#

Versioning#

Operational response headers#

CORS#