Xagent Docs
Get started

Authentication

Xagent supports interactive sign-in for the web app and API keys for programmatic access.

Sign In

Users sign in with their email address and password, or via Google single sign-on (OIDC). The first time the instance starts, an administrator account is created at /setup; afterwards, whether open registration is allowed is controlled by the deployment.

Sign in with your email address, not a username

Password sign-in identifies you by email. A username is no longer accepted as a login identifier — if you previously signed in with a username, use the email address on your account instead.

Log in:

POST /api/auth/login
GET  /api/auth/me
POST /api/auth/refresh
POST /api/auth/change-password

The request body takes exactly two fields — email and password. No other fields are accepted:

POST /api/auth/login
{
  "email": "ada@example.com",
  "password": "your-password"
}

A successful login returns a JWT access token plus a refresh token. Send the access token as a bearer header on subsequent requests:

Authorization: Bearer <access_token>
StatusMeaning
400Email cannot be empty or Please enter a valid email address.
401Incorrect email or password.
422The body contained an unexpected field — most commonly a legacy username field — or omitted email.
503Password login is temporarily unavailable.

Migrating an existing integration

A request body using the legacy username field now fails validation with 422 rather than signing in. Update any stored credentials or scripts to send email instead.

Google SSO

If Google OIDC is configured, users can sign in without a password:

GET /api/auth/oidc/google/login
GET /api/auth/oidc/google/callback

Personal API Keys

For scripting against your own account, mint a personal API key. The full key is shown once at creation — store it securely. This is the same key used to manage agents and templates through the Workspace API.

POST   /api/me/personal-keys      # create a key
GET    /api/me/personal-keys      # list key metadata
DELETE /api/me/personal-keys/{key_id}

Keys for the Workspace API

Programmatic access to the Workspace API (/v1) uses two key types:

KeyScopeFormat
Personal keyUser-scoped. Identifies you; manages agents and templates. Minted under Personal API Keys.xag_personal_<prefix>_<secret>
Runtime keyAgent-scoped. Runs tasks for a single agent. Generated when you create an agent or call its api-key endpoint.xag_<prefix>_<secret>

Both keys are sent as a bearer token and are shown in full only once at creation. The <prefix> is a public-safe 6-character handle used to identify a key in logs; the secret half is never retrievable again — rotate the key to replace it.

Team workspace keys

Separately from the user-scoped personal key, a team can issue workspace keys for team-wide SDK management via /api/teams/{team_id}/workspace-keys — see Teams & Workspaces.

Keep keys secret

API keys grant access to your agents and usage. Never commit them to source control or expose them in client-side code. Revoke and rotate any key you suspect is compromised.

Next Steps