API and Automation

Two surfaces: public verification endpoints (no auth, for consumers and AIs) and the integration API (with API key, for lab/seller systems operating machine-to-machine). Base URL: https://coa.extractoseum.com. Type: Reference. Audience: integrators and AIs. Status: v1 (2026-08-01, verified against the system). The in-depth lab integration manual lives in docs/api-manual/ (PDF + HTML). Have a Shopify store and want to sell EUM products? You don’t need this API — install the official app and use the app block. Go to Sell EUM on your Shopify (Collective).

​

Discovery for AIs / agents

• llms.txt — AI-readable index of the entire documentation (root of the docs site).
• GET https://coa.extractoseum.com/ara.md — system summary in Markdown, ready to import as an “external document” into an assistant.
• GET https://coa.extractoseum.com/ara.json — the same information in structured JSON.

​

A. Public verification endpoints (no authentication)

​

B. Integration API (machine-to-machine, with API key)

​

Authentication

• Header: X-EUM-Api-Key: <your_api_key> (opaque; hashed at rest).
• Scopes per key (validated per endpoint): orders:create, orders:read, samples:write.
• Rotation with grace period: when rotated, the previous key stays valid ~24 h (config) so integrations aren’t cut off.

​

Endpoints (/api/v1/integration/…)

Mandatory, validated tracking number: when registering the tracking number via API, the same rule as in the portal applies — it’s validated to be real (no “0000000000”), and without a tracking number the sample is not received at the laboratory.

​

Webhooks (signed notifications)

• Headers: X-EUM-Event, X-EUM-Delivery-Id, X-EUM-Timestamp (unix s), X-EUM-Signature.
• Signature: HMAC-SHA256 (base64) of the raw body with your endpoint’s secret.
• Always verify: recompute the HMAC and reject if it doesn’t match; also reject if the timestamp is >5 min off (anti-replay). Retries with backoff (2/10/30…) on failure.

import crypto from 'crypto';
function verify(rawBody, headers, secret) {
  const ts = Number(headers['x-eum-timestamp']);
  if (!ts || Math.abs(Date.now()/1000 - ts) > 300) return false;   // >5 min → replay
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64');
  const got = headers['x-eum-signature'] || '';
  return expected.length === got.length &&
         crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));
}

​

C. For AIs / agents

• Start with llms.txt — machine-readable index of these docs.
• The endpoints in section A require no auth: an AI can verify a Smart COA or a CVV directly.
• The integration API (section B) requires an API key with scopes — request it from the EUM team.
• Roadmap: an “eum-docs” agent skill (in the style of stripe-docs) so your AI can consume these docs and the API.