Developer Manual

Authentication

Every request except the health check is authenticated with a bearer API key. Keys begin with eck_live_ and carry their own organization and scopes — the server resolves your org from the key, so there is no separate organization header.

Bearer keys

Send your API key in the Authorization header as a bearer token. Live keys begin with eck_live_. The organization and scopes are attached to the key server-side.

bash

curl https://api.eclips.tech/v1/run \
  -H "Authorization: Bearer eck_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "agent_type": "procurement_specialist", "task": "Get 3 vendor quotes for 500 laptops" }'

In the SDK, pass the key to the constructor — nothing else is required:

typescript

import { EClipsClient } from "@eclips/sdk";

// The org and scopes ride on the key — there is no organizationId to pass.
const client = new EClipsClient({ apiKey: process.env.ECLIPS_API_KEY! });

Important:Treat keys as secrets. Never embed them in client-side code or commit them to source control. Store them in an environment variable or a secrets manager.

bash

# Store the key as a secret — never commit it.
export ECLIPS_API_KEY=eck_live_xxxxxxxxxxxxxxxxxxxxxxxx

Creating keys

Generate keys in the dashboard under Settings → API Keys. Select the scopes the key needs at creation time — scopes are enforced on every endpoint. The full eck_live_ value is shown once; copy it immediately. Keys can carry an optional expiry and can be revoked at any time (a revoked or expired key returns 401).

◳ Screenshot

Dashboard → Settings → API Keys: create a key, choose its scopes, and copy the eck_live_ value (shown once).

Scopes

A key only succeeds on an endpoint if it carries the matching scope; otherwise the API returns 403 Insufficient scope with the required and provided scopes in the body.

json

{
  "error": "Insufficient scope",
  "required": "agents:run",
  "provided": ["agents:read"]
}

agents:run	Trigger agent runs (POST /v1/run).
agents:read	Read runs, stream status, and read usage (GET /v1/runs, /v1/runs/:id, /v1/runs/:id/stream, /v1/usage*).
triage:read	List pending human-in-the-loop triage items (GET /v1/triage).
triage:write	Approve or reject triage items (POST /v1/triage/:id/approve\|reject).
webhooks:read	List registered webhooks (GET /v1/webhooks).
webhooks:write	Create and delete webhooks (POST /v1/webhooks, DELETE /v1/webhooks/:id).
batch:run	Create and cancel batch jobs (POST /v1/batches, POST /v1/batches/:id/cancel).
batch:read	List and read batch jobs (GET /v1/batches, GET /v1/batches/:id).

Note:Scope a key to exactly what an integration needs. A read-only dashboard, for example, needs only agents:read — not agents:run.

← PreviousQuickstart Next →REST API Reference