API Keys

API keys let you call the Ellaworks API from scripts, CI pipelines, and deployed agents without a browser session. Each key is scoped to a single organization.

Create an API key

1. Sign in to app.ellaworks.ai and select your organization
2. Navigate to Settings → API Keys
3. Click Create API Key, give it a descriptive name (e.g. ci-deploy, production-agent), and confirm
4. Copy the key immediately — it is only shown once

Use the key

Send your API key using either header below. The same key works across almost the entire API — see endpoints that require a browser session for the exceptions, which notably include managing API keys themselves.

X-API-Key

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://app.ellaworks.ai/api/environments?orgSlug=your-org"

Authorization: Bearer

Many HTTP clients and SDKs (including OpenAI-compatible libraries) send credentials as a Bearer token by default:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.ellaworks.ai/api/environments?orgSlug=your-org"

import OpenAI from "openai";
const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://app.ellaworks.ai/api", // use the path from the API reference for your endpoint
});

If you send both headers on the same request, X-API-Key takes precedence.

Missing or invalid keys return 401 Unauthorized. A valid key used on an endpoint that requires a browser session returns 401 as well.

A key is scoped to exactly one organization. Using it against a different organization fails as though the organization did not exist, even if the person who owns the key belongs to both.

By default a key acts as the user who created it. Admin-gated operations and per-resource grants are checked against that person’s access at the time of the request — so demoting someone, or revoking a grant, takes effect on their keys immediately, without needing to delete the keys.

The exception is delegated deployment approval, used when an integration (Ellavox) holds one org key and records approve/deny as a named required approver:

• Organization owners and admins can grant deployment:approve-as at key creation (allowApproveAs in Settings → API Keys). Existing keys cannot be upgraded; rotate the key to add the permission.
• A key with that permission must send actingUserEmail on approve/deny. The address is matched against this job’s required approvers (verified Ellaworks users only). It is not a search over the rest of the platform.
• The decision is logged via: ellavox. One such key can satisfy every vote in a multi-approver flow — that is why the grant is opt-in and admin-only.

Ordinary keys (no deployment:approve-as) still approve as the key owner when actingUserEmail is omitted.

Manage existing keys

From the Settings → API Keys page you can:

• View a list of all active keys with their names and creation dates
• Revoke a key you no longer need — revocation is immediate and cannot be undone

Security best practices

• Rotate regularly — create a new key and revoke the old one on a schedule that fits your security policy
• Use one key per integration — if a key is compromised you can revoke it without disrupting other systems
• Never commit keys to source control — use environment variables or a secrets manager instead
• Restrict network access where possible using firewall rules or allowlists

Next steps