Authentication #
HTTP Basic with an API key and secret. How to issue, send, rotate, and revoke credentials.
Every request to the DataDistillers API is authenticated with HTTP Basic. The username is your API key; the password is the matching secret. Both are issued together from the dashboard and the secret is shown exactly once.
Issuing credentials
A credential pair has two halves:
- API key (
dk_live_…ordk_test_…). Long-lived public identifier. Safe to log. - Secret (
sk_…). Sensitive. Stored hashed; the plaintext is shown one time at creation.
Generate a pair from the dashboard. Store the secret in a secret manager (AWS Secrets Manager, GCP Secret Manager, Vault, your CI's encrypted env). If you lose it, rotate; there's no recovery flow.
Sending the credentials
Every HTTP client supports HTTP Basic out of the box. The header is:
Authorization: Basic <base64(api_key + ":" + secret)>
HTTP Basic carries the secret in plaintext (under TLS). Never embed it in a browser bundle, mobile app, or any artifact you ship to a user. Proxy through a server you control.
Test vs live keys
Keys are prefixed by environment:
| Prefix | Environment | Notes |
|---|---|---|
dk_test_… | Sandbox | No charges. Synthetic results. Lower rate limits. |
dk_live_… | Production | Real charges. Real extraction. |
Match the prefix to the environment your code is running in. A live key in a test fixture will spend real wallet balance.
Rotating a secret
Rotate the secret on a schedule (most teams: every 90 days) and immediately if you suspect exposure.
- Issue a new secret for the same key from the dashboard.
- Deploy the new secret to your runtime config.
- Verify traffic with a
GET /wallethealth check. - Revoke the old secret in the dashboard.
The key (dk_live_…) stays the same; only the secret changes. There's no
hard cutover; old and new secrets are valid in parallel until you revoke.
Revoking a key
Revoking a key invalidates it immediately. In-flight requests using it return
401; queued jobs already accepted continue to completion. Webhook
deliveries that reference the key keep their signatures (the webhook secret is
separate from the API key secret).
Failure modes
| Status | Cause | Fix |
|---|---|---|
401 Unauthorized | Missing, malformed, or revoked credentials. | Re-check the Authorization header. Confirm the key isn't revoked. |
403 Forbidden | Key valid but lacks scope for the resource. | Issue a key with the right scope. |
429 Too Many Requests | Rate limit. | Back off. See Retry-After header. |
401 does not include a hint about whether the key or the secret is the
problem. This is intentional; leaking which half is wrong narrows brute-force
search. If you can't resolve it, rotate and try again.
Webhook signing secrets are different
The Authorization: Basic credential authenticates you to us (outbound
API calls). The webhook signing secret authenticates us to you (inbound
deliveries) via an HMAC over the request body.
The two have nothing in common. Rotating one does not rotate the other. See Webhook setup for the signing flow.