Authentication

All data endpoints require an API key passed via the API-KEY custom header. There is no OAuth flow, no Bearer tokens, no JWT — just a single header on every request.

curl "https://api.askedgar.com/v1/dilution-rating?ticker=AAPL" \
  -H "API-KEY: ask-live-a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12"

⚠️

The header name is API-KEY — not Authorization, not X-API-Key, not Bearer. Requests with the wrong header name will return a 401.

API key format

Keys follow this format:

ask-live-{64 hex characters}

For example: ask-live-a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12

The ask-live- prefix is always present and is part of the key itself — include it in the header value.

Creating and managing keys

Generate and manage API keys in the API Platform. From there you can create new keys, disable keys temporarily, or remove them entirely. A few things to know:

• The full key is only shown once at creation time. Copy it immediately and store it securely. After creation, the platform only displays a key hint (the first 12 characters, e.g. ask-live-a1b2) for identification.
• Keys don't expire automatically. You can disable or delete them at any time from the API Platform.
• Disabled keys return a 401 with error code api_key_disabled. Re-enable them from the API Platform whenever you're ready.
• Keys are hashed server-side. We store a SHA-256 hash of your key, not the key itself. If you lose it, you'll need to generate a new one.

Key permissions

API key access is controlled at two levels:

Organization level — Your plan determines which endpoints your organization can access. All keys in the organization inherit these permissions by default.

Key level — Individual keys can be further restricted to a subset of your organization's available endpoints. This is useful if you want to issue a key that can only access specific data (e.g., a key limited to dilution data for a downstream integration).

If a key doesn't have explicit endpoint restrictions, it inherits full access from the organization.

Public endpoints (no key required)

A few endpoints are publicly accessible without authentication:

The cost estimate endpoint is particularly useful — it lets you preview costs without spending any credits.

Authentication errors

All auth errors follow the standard error envelope:

{
  "status": "error",
  "error": {
    "code": "missing_api_key",
    "message": "API key is required. Pass it in the API-KEY header.",
    "details": {}
  },
  "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

The request_id is also returned as an X-Request-ID response header. Include it if you contact support about a failed request.

Security headers

Every response from the API includes the following security headers:

Request lifecycle

When a request hits the API, it passes through these checks in order:

1. Authentication — Is a valid API key present?
2. Endpoint permissions — Does this key have access to the requested endpoint?
3. Rate limiting — Has the organization exceeded its per-minute request limit?
4. Credit check — Does the organization have enough credits for this request?
5. Ticker limit (trial only) — Has the daily unique ticker limit been exceeded?
6. Request processing — The endpoint logic runs and returns data.

If any step fails, the API returns the corresponding error immediately and does not proceed further. This means a 401 always takes priority over a 429, and a 429 takes priority over a 402.

Best practices

• Never hardcode keys in source code. Use environment variables or a secrets manager.
• Use separate keys for separate integrations. If one key is compromised, you only need to rotate that one.
• Restrict key permissions when a key only needs access to specific endpoints.
• Rotate keys periodically. Generate a new key, update your integration, then disable the old one.
• Don't log the full key. If you need to identify a key in logs, use the first 12 characters (the key hint).

Next steps