Skip to main content

API Key + HMAC

Use this page for Auto integrations on /v2/auto/*. If you still need to choose between API key and x402 models, start with Auto Overview.

Base URL​

https://api.elfa.ai/v2/auto

Developer Portal Setup​

Auto must be enabled per API key in the Developer Portal:

  1. Open https://dev.elfa.ai/.
  2. Open your API key and go to the Auto tab.
  3. Enable Auto for that key and copy the generated HMAC secret.

The Auto tab currently shows a quick-start example using a legacy route form:

# Sign requests with HMAC-SHA256
SIGNATURE=$(echo -n "${TIMESTAMP}POST/v2/athena/queries${BODY}" | \
  openssl dgst -sha256 -hmac "${HMAC_SECRET}" -hex | awk '{print $2}')

curl -X POST https://api.elfa.ai/v2/athena/queries \
  -H "x-elfa-api-key: ${API_KEY}" \
  -H "x-elfa-signature: ${SIGNATURE}" \
  -H "x-elfa-timestamp: ${TIMESTAMP}" \
  -H "Content-Type: application/json" \
  -d "${BODY}"

For documented /v2/auto/* endpoints, keep the same signing model but follow the mounted-path rule in this guide (/queries, /chat, etc.).

Required Headers​

All /v2/auto/* routes require:

  • x-elfa-api-key

Mutation routes also require:

  • x-elfa-signature
  • x-elfa-timestamp

HMAC Signing​

Headers:

x-elfa-signature: <hex_hmac_sha256>
x-elfa-timestamp: <unix_seconds>

Payload format:

timestamp + method + path + body

Where:

  • timestamp: unix seconds
  • method: uppercase HTTP method
  • path: route path verified by Auto router
  • body: exact JSON string body, or empty string

Replay window: +/-30 seconds.

Important mounted-router detail:

  • Request URL may be /v2/auto/queries
  • Signature path must be /queries (the mounted router path)

Using /v2/auto/queries in the signed payload will fail verification.

Concrete Signing Example​

Example target endpoint: POST /v2/auto/queries

import crypto from "crypto";

const hmacSecret = process.env.ELFA_HMAC_SECRET!;
const timestamp = Math.floor(Date.now() / 1000).toString();
const method = "POST";
const path = "/queries"; // mounted path (NOT /v2/auto/queries)

const bodyObj = {
  title: "BTC Alert",
  query: {
    conditions: {
      AND: [
        {
          source: "price",
          method: "current",
          args: { symbol: "BTC" },
          operator: ">",
          value: 100000,
        },
      ],
    },
    actions: [
      {
        stepId: "step_1",
        type: "notify",
        params: { message: "BTC crossed target" },
      },
    ],
    expiresIn: "24h",
  },
};

const body = JSON.stringify(bodyObj);
const payload = `${timestamp}${method}${path}${body}`;
const signature = crypto
  .createHmac("sha256", hmacSecret)
  .update(payload)
  .digest("hex");

console.log({ timestamp, signature, body });

Then send:

POST /v2/auto/queries
x-elfa-api-key: <api_key>
x-elfa-timestamp: <timestamp>
x-elfa-signature: <signature>
content-type: application/json

<body exactly as signed>

No-body example (DELETE /v2/auto/queries/{id}): sign with path = "/queries/{id}" and body = "".

Enablement Requirements​

API keys must be Auto-enabled and linked to a user identity in the Developer Portal. If not enabled/linked, /v2/auto/* returns 403.

Endpoint Matrix​

Mounted endpoints below are the routes inside /v2/auto.

Queries and Drafts​

EndpointHMAC
GET /queriesNo
GET /queries/:idNo
GET /queries/:id/evaluationsNo
GET /queries/:id/streamNo
GET /queries/:id/sessionsNo
GET /queries/:id/sessions/:sessionIdNo
POST /queries/validateNo
POST /queries/previewNo
POST /queriesYes
DELETE /queries/:idYes
GET /queries/draftsNo
GET /queries/drafts/:idNo
POST /queries/draftsNo
DELETE /queries/drafts/:idNo
POST /queries/drafts/:id/previewNo
POST /queries/drafts/:id/convertYes

Executions​

EndpointHMAC
GET /executionsNo
GET /executions/:idNo

Chat​

EndpointHMAC
POST /chatYes

Common Errors​

  • 401: missing/invalid key, signature, timestamp, or clock skew
  • 403: Auto not enabled for the API key or no linked user
  • 422: validation failure (query content)