Authentication
Call the Lucy data API from your server with a personal API key.
API keys#
An API key lets your server call the data API without a browser session. Requests made with a key act as your account and draw on your plan.
- Keys are issued by an administrator. Contact us to request one.
- The full key is shown once, when it is issued, and cannot be retrieved later. Store it right away; if it is lost, ask for it to be revoked and reissued.
- Keys expire after 30–365 days (default 90); there are no non-expiring keys. An account can hold up to 5 active keys.
- See your keys, their expiry and when each was last used on your API keys page.
Making requests#
Send the key in the X-API-Key header of every request:
X-API-Key: lucy_v1_<public_id>_<secret>- Keys look like
lucy_v1_<public_id>_<secret>: a 16-character hex public ID and a 43-character secret, 68 characters in total. - Only GET and HEAD requests are accepted.
- Every response, including errors, is JSON. There are no redirects; a request that is not authorized gets an error status, never a sign-in page.
- Call the API from your backend. Browser cross-origin calls are not supported (no CORS).
Plan limits#
- Every API key request counts toward the key owner's plan: one request against the per-minute limit and one against the monthly limit.
- Your signed-in session and all of your keys share one quota. More keys do not mean more quota.
Errors#
Errors are JSON with a single error field (402 may add resetAt).
| Status | Body | Meaning |
|---|---|---|
| 400 | — | Invalid request parameters. Fix the request. |
| 401 | {"error":"Unauthorized"} | Missing, malformed, unknown, expired or revoked key. Every case returns the same body. |
| 402 | {"error":"Monthly limit reached","resetAt":"…"} | Your plan's monthly quota is used up. resetAt, when present, is when it resets. |
| 403 | {"error":"Account suspended"} | The key owner's account is suspended. |
| 403 | {"error":"Forbidden"} | The endpoint or method is not available to API keys. |
| 404 | — | The ticker, fund or dataset was not found. |
| 429 | {"error":"Too Many Requests"} | Rate limited, with a Retry-After header: your plan's per-minute limit, the per-IP limit (1,000 requests per 15 minutes), or too many failed key attempts from one IP (20 per 15 minutes). |
| 503 | {"error":"Service Unavailable"} | Temporarily unavailable, including key verification. Retry with backoff. |
Retries#
- 429: wait for the
Retry-Afterseconds, then retry. - 503: retry with exponential backoff.
- Do not retry 401, 402 or 403; they will not succeed until the key, the plan or the account changes. Repeated failed key attempts also trigger the per-IP failure limit.
Security#
- Use HTTPS only.
- Keep the key in a server-side environment variable or secret store. Never put it in browser bundles, mobile apps, repositories or URLs.
- Mask the key in logs and error reports.
- If a key leaks, ask an administrator to revoke it; a revoked key stops working immediately. Check when your keys were last used on your API keys page.