Answer: ASHDOCS authenticates every API call with an X-API-Key header. Keys come in two kinds: sandbox keys (prefix ash_test_) that run every tool end-to-end but never charge credits, and live keys (prefix ash_live_) that deduct from your plan on success. Keys are stored hashed — the plaintext is shown exactly once at creation.
Sending your key
Pass the key on every request in the X-API-Key header. Nothing else changes between sandbox and live — same endpoints, same request and response shapes.
curl -X POST https://www.ashdocs.com/api/v1/tools/html-to-pdf \
-H "X-API-Key: ash_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "html": "<h1>Invoice</h1>" }'Test vs live keys
ash_test_ keys execute the full pipeline (real conversion, real output files) with credits_consumed always 0 — use them in CI and development freely; you can create as many sandbox keys as you like. ash_live_ keys bill credits on successful jobs only; failed jobs are never charged. Live key count is capped per plan: Free 1, Starter 3, Growth 10, Pro 25, Scale 50.
Creating, naming and revoking keys
Create keys in the dashboard at /keys or via the API. The plaintext key appears once in the creation response and is never retrievable again (only a SHA-256 hash is stored server-side). Revocation is immediate — the next request with a revoked key gets 401.
# create (the response's "api_key" field is shown ONCE)
curl -X POST https://www.ashdocs.com/api/api-keys \
-H "Content-Type: application/json" -H "Authorization: Bearer <session JWT>" \
-d '{ "name": "prod-invoicing", "environment": "live" }'
# revoke
curl -X DELETE https://www.ashdocs.com/api/api-keys/<api_key_id> \
-H "Authorization: Bearer <session JWT>"Key scoping
A key belongs to your account (or your team workspace — teammates share the same key pool) and can call every tool your plan includes. There are no per-tool scopes today; if you need blast-radius separation, issue one named key per service and revoke independently.
Rotation, and what revocation does NOT stop
Zero-downtime rotation: create the new key, deploy it, then revoke the old one — both stay valid during the rollover. Revoking a key stops new API requests immediately, but it does not cancel jobs already running, and it does not pause Flows: scheduled flows authenticate internally and connectors use their own stored connections, so they keep running until you turn the flow off.
Auth errors you'll see
A missing or unknown key on a key-authenticated endpoint returns 401 with detail "Invalid API key". Hitting your plan's live-key cap returns 400 with a plain message naming the limit. Endpoints gated to higher plans (for example /v1/batch on Free) return 403 with a code like batch_not_available.
Frequently asked questions
Can I retrieve a lost API key?
No. Only a hash is stored. Revoke the lost key and create a new one — creation takes seconds and rotation is zero-downtime.
Do sandbox keys have a lower rate limit?
No — rate limits are per plan, not per key kind. A Free-plan sandbox key gets the same 10 requests/minute as a Free-plan live key.
Does revoking a key stop my scheduled Flows?
No. Flows authenticate internally and connectors use their own stored connections. Turn a flow Off in the builder to stop it.