Authentication

Endpointwise uses API keys for all gateway authentication. Keys can be scoped, time-limited, and rotated without downtime.

Request format

Send your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0...

Alternatively, pass it as a query parameter (not recommended for production):

GET /v1/invoices?api_key=sk_live_a1b2c3...

Key scopes

Every key has a scope that restricts what actions it can perform. Available scopes:

Scope	Allowed operations
`read`	GET requests to all allowed endpoints
`write`	GET + POST + PUT + PATCH to all allowed endpoints
`admin`	All methods including DELETE
`read:invoices`	GET to `/v1/invoices/*` only (path-specific scope)

Path-specific scopes follow the format scope:resource and restrict the key to endpoints matching that resource prefix in your OpenAPI spec's path structure.

Key expiry

Set an expiry date when creating a key. After the expiry date, the key returns 401 Unauthorized. Keys without an explicit expiry are valid indefinitely until revoked.

npx endpointwise keys create \
  --name "Partner: Acme Corp" \
  --scope read \
  --expires 2026-12-31

Key rotation (zero-downtime)

Rotating a key without downtime is a three-step process:

Issue a new key with the same scope
Configure an overlap window — both the old and new key are valid during this period
After your partner switches to the new key, revoke the old one

npx endpointwise keys rotate \
  --key-id key_abc123 \
  --overlap-days 14

During the overlap window, the traffic attribution panel in the dashboard shows which key is being used by which requests, so you can confirm the transition.

Key values shown once: Endpointwise stores only a hash of the key value. The full key string is shown at creation time only. If a key is lost, revoke it and issue a new one.

401 and 403 responses

Authentication failures return the following error codes:

Status	Reason
`401`	Missing or invalid key, expired key
`403`	Key is valid but scope insufficient for the requested operation

The response body includes a code field (key_expired, key_invalid, scope_insufficient) for programmatic handling.

Audit log

Every authentication event is logged, keyed by the key's truncated prefix. Access the log from the dashboard under Keys → Audit log. Logs are retained for 90 days on the Starter plan, 365 days on Platform and Scale.