Authentication

Overview

Catalog endpoints under https://epochalstock.com/api/v1 require authentication. Send your key on every request alongside an explicit JSON accept header. Keys are prefixed es_test_ (free trial, issued instantly by POST /trial/signup) or es_live_ (paid) — both use the same header and endpoints:

Authorization: Bearer es_live_…your_secret…
Accept: application/json

Why Bearer-only

Passing secrets as query parameters is convenient and wrong. URLs leak into browser history, reverse proxies, CDN access logs, analytics beacons, crash reports, and support screenshots. Bearer headers stay out of the request line and are far less likely to be retained by intermediate systems that log full URLs.

The API therefore rejects patterns such as ?api_key=… or ?key=… and returns query_key_rejected (HTTP 400). Always place the secret in the header:

• Use Authorization: Bearer <key> on every authenticated call.
• Send Accept: application/json so error bodies stay machine-readable.
• Load the key from an environment variable or secrets manager—never hard-code it.
• Call the API only from a trusted server. Public browsers must not hold live keys.

Request flow

How an authenticated catalog request is processed from client to handler.

Failed validation never reaches catalog handlers. Invalid or revoked keys return invalid_api_key; inactive billing returns subscription errors; browser/CORS misuse returns cors_not_supported. Successful responses always include X-Request-ID and rate-limit headers.

Header examples

The snippets below show the minimum headers for a simple GET https://epochalstock.com/api/v1/images call. Replace the environment variable with your secret store of choice. Never commit real keys.

curl -sS "https://epochalstock.com/api/v1/images?limit=5" \
  -H "Authorization: Bearer $EPOCHAL_API_KEY" \
  -H "Accept: application/json" \
  -D -

const response = await fetch(
  "https://epochalstock.com/api/v1/images?limit=5",
  {
    headers: {
      Authorization: `Bearer ${process.env.EPOCHAL_API_KEY}`,
      Accept: "application/json",
    },
  }
);

const requestId = response.headers.get("x-request-id");
if (!response.ok) {
  throw new Error(`HTTP ${response.status} request_id=${requestId}`);
}
const body = await response.json();

$ch = curl_init('https://epochalstock.com/api/v1/images?limit=5');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('EPOCHAL_API_KEY'),
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT => 20,
]);
$raw = curl_exec($ch);
// Split headers/body, read X-Request-ID, then json_decode the body.

import os
import requests

r = requests.get(
    "https://epochalstock.com/api/v1/images",
    params={"limit": 5},
    headers={
        "Authorization": f"Bearer {os.environ['EPOCHAL_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=20,
)
request_id = r.headers.get("X-Request-ID")
r.raise_for_status()
print(request_id, r.json())

package main

import (
    "fmt"
    "net/http"
    "os"
    "time"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://epochalstock.com/api/v1/images?limit=5", nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("EPOCHAL_API_KEY"))
    req.Header.Set("Accept", "application/json")

    client := &http.Client{Timeout: 20 * time.Second}
    res, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()
    fmt.Println("X-Request-ID:", res.Header.Get("X-Request-ID"))
}

Key lifecycle

Each account may hold up to 20 named keys. Create a separate key per website, backend, or environment so you can revoke one project without rotating everything. All keys on an account share the same rate limit and concurrent-download lease.

1. Create — After an active subscription, call the management API (POST /keys) with a human-readable name such as design-app-prod. Copy the secret immediately; it is not shown again.
2. Name & store — Save the secret in a vault or environment variable scoped to that deployment. Document which service owns the key.
3. Use — Attach the Bearer header from server-side code only. Monitor usage per day via the portal usage endpoint.
4. Rotate — Create a new named key, deploy it, confirm traffic, then revoke the old key. Do not reuse compromised secrets.
5. Revoke — DELETE /keys/{key_id} invalidates a key immediately. In-flight clients will start receiving invalid_api_key.

Management calls (list/create/revoke keys, billing, usage) live behind the portal session and CSRF protection—not the Bearer catalog key. See Security & billing for portal flows.

Request ID troubleshooting

Every API response includes an X-Request-ID header (and often a matching request_id field inside error JSON). Treat it as the primary correlation token when something fails in production.

Successful JSON bodies also carry meta.request_id. Prefer logging both the header and body ID when available so retries and multi-hop proxies stay aligned.

Common authentication errors

Auth-related failures return structured JSON with error.code, error.message, and error.request_id. The table below lists the codes you will see most often while wiring credentials.

For rate limits, validation errors, and the full error catalog, see Rate limits & errors.

Security rules

• Store keys in a secrets manager or environment variables—never in git, screenshots, or chat.
• Issue one named key per project or environment; revoke the smallest blast radius on compromise.
• Reject putting keys in URLs, form fields, localStorage, or analytics payloads.
• Set connect and read timeouts on every HTTP client.
• Retry only 429, 502, and 503 with bounded exponential backoff and jitter.
• Rotate keys periodically and immediately after any suspected exposure.
• Treat download URLs as short-lived secrets; do not log them in analytics.