Authentication & Limits

Platform API: `x-api-key`

Most v1 endpoints are Platform API endpoints and require an API key header:

x-api-key: <your_api_key>

If the key is missing or invalid, you’ll receive a 401 error.

Scopes

Most v1 endpoints currently require:

assets:read

Some endpoints may accept a fine-grained scope in addition to assets:read. For example, GET /v1/assets/risk-summary accepts either assets:read or assets:risk:read.

If your key doesn’t have the required scope, you’ll receive a 403 error.

Request IDs

Platform endpoints include:

x-request-id header on responses

If you contact support, include the x-request-id.

Rate limits and errors

For limit behavior, retry patterns, and common status codes, see:

Rate Limits & Errors

Example (TypeScript + fetch)

interface ApiErrorEnvelope {
  error: {
    _tag: string;
    message: string;
    details?: unknown;
  };
}

function isApiErrorEnvelope(value: unknown): value is ApiErrorEnvelope {
  if (!value || typeof value !== "object") return false;
  const error = (value as { error?: unknown }).error;
  if (!error || typeof error !== "object") return false;
  const e = error as { _tag?: unknown; message?: unknown };
  return typeof e._tag === "string" && typeof e.message === "string";
}

export async function getJson<T>(path: string, apiKey: string): Promise<T> {
  const res = await fetch(path, {
    headers: { "x-api-key": apiKey },
  });

  const json: unknown = await res.json().catch(() => null);

  if (!res.ok) {
    if (isApiErrorEnvelope(json)) throw new Error(`${json.error._tag}: ${json.error.message}`);
    throw new Error(`HTTP ${res.status}`);
  }

  return json as T;
}