Authentication

Everything in AgentX authenticates with a project API key sent as an x-api-key header. The dashboard, the Python SDK, CI pipelines, and OpenTelemetry exporters all use the same key.

x-api-key: agtx_local_...

Where keys come from

Engine startup log: the line Default project API key: agtx_local_... prints on every boot. This is the canonical copy source for a fresh instance - there is no anonymous key endpoint.
Dashboard: once connected, Settings → API access shows the current project’s key, and each project you create gets its own key (the project switcher moves between them).

Dashboard: the connect screen

The default self-host mode has no user accounts - the first visit to the dashboard asks for a project API key instead. Paste the key from the startup log; it’s validated against the engine, stored in that browser’s local storage, and attached to every request from then on. The sidebar’s Disconnect button forgets it.

SDK

from agentx import AgentX

# From the environment (AGENTX_API_KEY, plus AGENTX_API_BASE_URL for self-host)
client = AgentX.from_env()

# Explicit
client = AgentX(
    api_key="agtx_local_...",
    base_url="http://localhost:4700/api/v1",
)

export AGENTX_API_BASE_URL=http://localhost:4700/api/v1
export AGENTX_API_KEY=agtx_local_...

The three modes

	Default (no auth)	`AGENTX_AUTH=enabled`	+ `AGENTX_MULTI_TENANT=true`
For	Local testing, single operator	A self-host team sharing one instance	A multi-tenant deployment (this is how AgentX’s own cloud runs)
Dashboard	Auto-connects, no accounts	Email + password session	Email + password session
Signup → org	n/a	First user owns the instance; later signups join the same org	Every signup gets its own organization + a seeded default project
Teammates	n/a	Just sign up	Invited (Settings → Team), roles: owner/admin/member
LLM provider keys	Env or Settings	Env or Settings, instance-wide	Per-organization only - the env is never used for tenant traffic
Pricing catalog	Instance-wide	Instance-wide	Global read-only defaults + per-org additions
SDK / CI / OTel	`x-api-key`	`x-api-key` (unchanged)	`x-api-key` (unchanged)

Multi-user mode: `AGENTX_AUTH=enabled`

For a shared instance, start the engine with AGENTX_AUTH=enabled. This switches the dashboard from the connect screen to real accounts:

First boot shows an owner-setup screen - the first account created becomes the organization owner and claims the existing projects. Later sign-ups join as members.
Dashboard requests ride the session cookie; project keys are handed out through the session-guarded /projects listing after sign-in, never anonymously.
SDK / CI / OTel callers are unchanged - they still authenticate with a project API key from Settings → API access.

Multi-tenant mode: `AGENTX_MULTI_TENANT=true`

Add AGENTX_MULTI_TENANT=true (with auth enabled) for a deployment where strangers sign up - each signup creates its own organization with a seeded default project, and organizations are hard-isolated: separate projects and data, separate LLM provider keys (Settings → LLM Providers writes the org’s own row; the process env is never used for tenant judge calls), and separate pricing-catalog additions. Teams and invitations (Settings → Team): owners and admins invite teammates by email - creating an invitation returns a link to send; the teammate signs in (or signs up) with the invited email and the link adds them to the organization. Invitations are single-use, bound to the invited email, and expire after 7 days. The owner can’t be removed; admins can invite and remove members. Set AGENTX_PUBLIC_URL so invitation links carry your real domain. All of these are optional and advertised to the dashboard through /auth/config, so the sign-in screen only shows what the engine actually supports:

Email delivery: configure AGENTX_RESEND_API_KEY (Resend) or AGENTX_SMTP_URL (any SMTP server), plus AGENTX_EMAIL_FROM. With a transport configured, invitation emails are sent automatically and the sign-in screen gains a Forgot password? link that emails a reset link (/reset-password in the dashboard).
Email verification: add AGENTX_REQUIRE_EMAIL_VERIFICATION=true to make new accounts verify their address before the first sign-in.
Social sign-in: set AGENTX_GOOGLE_CLIENT_ID/AGENTX_GOOGLE_CLIENT_SECRET and/or AGENTX_GITHUB_CLIENT_ID/AGENTX_GITHUB_CLIENT_SECRET to add “Continue with Google/GitHub” buttons. Register the OAuth callback as <AGENTX_PUBLIC_URL>/api/v1/auth/callback/<provider>.

Operating a multi-tenant deployment

Quotas: AGENTX_QUOTA_JUDGE_CALLS_PER_DAY caps judge LLM spend (per organization in multi-tenant mode) and AGENTX_QUOTA_TRACES_PER_DAY caps root-trace ingest per project. Hitting a quota returns a clear error naming the limit; both reset at midnight and are unlimited when unset.
Admin overview: set AGENTX_ADMIN_TOKEN and call GET /api/v1/admin/overview with an x-admin-token header for per-organization members, projects, and 24-hour judge/trace usage. The endpoint 404s when the token is unset.
Organization deletion: an owner can delete their organization from the API (DELETE /api/v1/auth-org/organizations/:orgId with the org name as confirmation) - every project and all of its data go with it. User accounts survive; in multi-tenant mode a returning orphaned account simply gets a fresh organization.

Putting it together

A complete multi-tenant cloud posture is just environment variables on the same engine binary or Docker image the single-tenant install uses:

AGENTX_AUTH=enabled
AGENTX_MULTI_TENANT=true
AGENTX_PUBLIC_URL=https://eval.example.com
AGENTX_DB_URL=postgres://...           # Postgres recommended for a public deployment
AGENTX_RESEND_API_KEY=re_...           # or AGENTX_SMTP_URL
AGENTX_EMAIL_FROM="AgentX <noreply@example.com>"
AGENTX_REQUIRE_EMAIL_VERIFICATION=true
AGENTX_GOOGLE_CLIENT_ID=...            # optional social sign-in
AGENTX_GOOGLE_CLIENT_SECRET=...
AGENTX_QUOTA_JUDGE_CALLS_PER_DAY=500
AGENTX_QUOTA_TRACES_PER_DAY=10000
AGENTX_ADMIN_TOKEN=<long random secret>

Related engine variables (AGENTX_PUBLIC_URL, AGENTX_TRUSTED_ORIGINS, the mailer, quota, and admin variables) are listed in Configuration.

Security model

A project API key grants full access to that project’s data - treat it like any other secret: environment variables and CI secret stores, never source control. In default mode the engine trusts the network boundary (“if you can reach the port, you hold a key you were given”), so bind it to localhost or a private network, or turn on AGENTX_AUTH=enabled before exposing it more widely.

Get Started

Self-Hosting

Python SDK

Authentication

Where keys come from

Dashboard: the connect screen

SDK

The three modes

Multi-user mode: `AGENTX_AUTH=enabled`

Multi-tenant mode: `AGENTX_MULTI_TENANT=true`

Operating a multi-tenant deployment

Putting it together

Security model

​Where keys come from

​Dashboard: the connect screen

​SDK

​The three modes

​Multi-user mode: AGENTX_AUTH=enabled

​Multi-tenant mode: AGENTX_MULTI_TENANT=true

​Email, password reset, and social sign-in

​Operating a multi-tenant deployment

​Putting it together

​Security model

Where keys come from

Dashboard: the connect screen

SDK

The three modes

Multi-user mode: `AGENTX_AUTH=enabled`

Multi-tenant mode: `AGENTX_MULTI_TENANT=true`

Email, password reset, and social sign-in

Operating a multi-tenant deployment

Putting it together

Security model