API authentication and idempotency

Authentication

Use Authorization: Bearer ck_live_…. Keys are stored as hashes, can be revoked immediately, and should never appear in URLs, logs, CSV files, or browser code.

Scopes separate certificate reading, issuing, and revocation. A valid key without the required scope returns insufficient_scope.

Idempotency keys

Idempotency-Key is optional for certificate creation and strongly recommended for every retryable integration. Use a stable identifier for one logical operation.

Same key and same raw JSON returns the stored response.
Same key and different raw JSON returns idempotency_key_reused.
A request still completing returns idempotency_in_progress; retry after the supplied delay.
external_id is a second workspace-level duplicate guard.

Rate limits

Read RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After. Back off with jitter after rate_limit_exceeded.

Pagination

List endpoints return opaque next_cursor values. Send them back unchanged. Do not decode or construct cursors.