> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ellaworks.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ellaworks.ai/_mcp/server.

# 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](https://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

> **Warning**
>
> Store your API key in a secrets manager or environment variable. If you lose it, revoke the old key and create a new one.

## 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](/api-reference#endpoints-that-require-a-browser-session)
for the exceptions, which notably include managing API keys themselves.

### `X-API-Key`

```bash
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:

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

```typescript
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

> **Note**
>
> API keys inherit the permissions of the organization they belong to. Any key for an organization can access all registries, agents, and environments within that organization.

## 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

#### [API Reference](/api-reference)

Explore the available endpoints

#### [Creating an Account](/creating-an-account)

Set up your account and organization