API authentication

Programmatic clients can authenticate with an organization API key using either header:

• X-API-Key: YOUR_API_KEY
• Authorization: Bearer YOUR_API_KEY (OpenAI-SDK-compatible)

If both are sent on the same request, X-API-Key takes precedence.

Keys use the ela_ prefix. Create and revoke keys under Settings → API Keys in the app.

A key's name is at most 32 characters. When you create a key you can give it an expiration date, from tomorrow up to 365 days ahead; leave the date empty for a key that never expires. An expiring key stops working during the day you picked (UTC) and then answers 401. Its owner is notified in the app before that happens. A key's expiry cannot be changed afterwards: create a new key and revoke the old one.

A key may make 1000 requests before it has to pause for a second. The count starts over only when a request arrives more than one second after the last accepted one, so a client that never leaves that gap gets 429 with data.code API_KEY_RATE_LIMITED from request 1001. Wait data.retryAfterMs milliseconds (at most 1000) and retry.

A key acts as the user who created it — admin-level operations and resource grants are checked against that person's current access — and is scoped to a single organization. It works on almost every endpoint, including all of /tools, /agents (creation, deployment, and imports), /knowledge-bases (including documents and gaps), and /environments and its secrets. A key resolves a knowledge gap only when its owner is an approver for that gap.

These still require a signed-in browser session and return 401 for a key: GET/POST /api-keys, /onboarding/*, PATCH /decisions/settings, /audit-logs, /deployments (deployment history), /fleets, and POST/PATCH/DELETE /registries. Each endpoint's page in the API reference states what it accepts.

What a key can ask about itself

Three calls are about the credential making the request. Every key can make them, including a key issued by agx login, which is otherwise limited to Elladex listings and domains.

• Who am I. GET /api/account/principal returns the user the key acts as (the email address is masked, a•••@acme.com), the organization the key is bound to with the owner's current role there, and the key's id, name, first characters, scopes and expiry. It never returns the key itself. A browser session gets organization: null and apiKey: null. If the key's owner has left the organization the call still answers 200, with organization: null and the key's own details, so the key can find its id and revoke itself. Calls that act in the organization answer such a key 403 with data.code: "API_KEY_OWNER_NOT_MEMBER".
• Which organizations. GET /api/organizations lists the caller's organizations and their role in each. A key issued by agx login sees only the organization it is bound to. Other keys, and browser sessions, see every organization the user belongs to.
• Log out. DELETE /api/api-keys/{apiKeyId} with the key's own id revokes it. The next request with that key gets 401 with data.code: "API_KEY_INVALID". A key cannot delete any other key (403, data.code: "API_KEY_SELF_REVOKE_ONLY"); use Settings → API Keys for that. agx logout does exactly this.

Keys from agx login

The agx command-line tool does not need a key from Settings. agx login opens /auth/device in your browser, where you sign in, check the code the terminal is showing, choose the organization the key is for and approve. You must be an owner or admin of that organization. You can create a new organization on the same page.

A key issued this way is narrower than one you create in Settings:

• It works for Elladex listings and domains only (listings:read, listings:write, domains:read, domains:write). Any other endpoint answers 403 with data.code: "INSUFFICIENT_SCOPE".
• It is bound to the one organization you approved.
• It expires after 90 days. Run agx login again to get a new one.

It appears under Settings → API Keys with the client (agx), the device name the tool reported, the organization and the expiry date, and you can revoke it there at any time. You get an email when a key is issued this way; if you did not expect it, revoke the key.

Only approve a sign-in you started yourself. The client name on the page comes from our list of known clients, and any software can ask under that name, so it is not proof of what sent the request. The approval page shows the code, the device name and the address the request came from so that you can check.

Making a listing public needs a person

A key issued by agx login can create, edit and publish Elladex listings, but it cannot put one in the public directory. Two requests are refused with 403 and data.code: "HUMAN_CONFIRMATION_REQUIRED":

• POST /agent-index/listings/{listingId}/publications on a listing whose visibility is public;
• PATCH /agent-index/listings/{listingId} setting visibility to public on a listing that is already published. None of that update is applied.

The response's data.url is the listing's page, where an organization admin signs in and confirms with one click:

• Publish to public directory, when the listing is not published yet;
• Make public, when it is already published as private or unlisted.

Publishing a private or unlisted listing, and setting public on a draft so that it is ready for that click, both work as usual. Keys created under Settings → API Keys are not affected.

POST /agent-index/listings/{listingId}/publications also accepts an optional expectedVisibility. When the listing's stored visibility is different, nothing is published and the answer is 409. The listing's page sends it, so a click there never publishes at a visibility the page did not show.

For full examples (curl, OpenAI SDK, proxy URLs), see the published API reference (API Keys and API Reference sections).

Limit an integration to agent tags

In Settings → API Keys, choose the organization, select Selected agent tags, and choose the tags for the business client. Preview the matching agents and dependency counts before creating the key. A key matches an agent when they share any selected tag. Existing keys keep their organization-wide access.

The server limits the key to those agents and their referenced knowledge bases, prompts, promptlets, and tools. Dependencies are followed forward: sharing a tool with another agent does not grant access to that agent. A referenced KB is included because it is an agent dependency; this does not create a separate customer ownership field on the KB.

Connect Ellavox with the new key and the existing organization slug and environment settings. An empty allowed list is a valid connection. Direct resource requests are checked as well as lists. Unsupported API surfaces are denied to restricted keys. Existing membership, resource grants, and deployment approval permissions still apply.

Manage access-defining tags and agent references in Elacity with your normal session. A restricted integration key cannot rewrite its own grant by changing those fields. To change the key's tag selection, create a replacement key and rotate the integration.

Agent tags and references are read for each API request. MCP API-key introspection and Ellavox agent lists may retain their existing 60-second cache windows. Deployed agents use separate signed MCP tokens scoped to their deployment's KBs; rotating an integration key does not revoke a deployed agent's token or remove text already compiled into its provider prompt.