Xagent Docs
Get started

Access & Authentication

Xagent Cloud is a hosted service — there is nothing to install. You use it in your browser at cloud.xagent.co, and you reach it programmatically using the APIs described here.

Looking for the app instead?

If you just want to sign up and start using Xagent, see the Quickstart. This page is for calling Xagent from your own code.

Base URL

Xagent Cloud runs in two regions. Use the base URL for the region your account belongs to — the one you chose when you registered.

Singapore:   https://sg-origin.cloud.xagent.co
Australia:   https://au-origin.cloud.xagent.co

Do not call the app hostname directly

cloud.xagent.co is the address you use in a browser. API and SDK calls must go to your regional origin above. A request to the app hostname carries no signed-in session for the edge to route on, so it will not reach your region and can fail in a way that looks like an authentication error.

Self-hosted deployments are addressed differently — see Self-Hosting.

The Three Ways In

SurfaceCredentialUse it for
Workspace SDK /v1Personal key or runtime keyManaging agents and running tasks — the stable, versioned surface. Start here.
App API /apiJWT access tokenThe same endpoints the web app uses. Broader, less stable.
External / Partner API /v1/externalOAuth client credentialsAn application acting on behalf of its own end users.

API Keys

Two key types cover the Workspace SDK. Both are sent as a bearer token and both are shown in full only once — store them securely, because you cannot retrieve them again, only rotate them.

KeyScopeFormat
Personal keyUser-scoped. Identifies you; manages agents and templates.xag_personal_<prefix>_<secret>
Runtime keyBound to a single agent or workforce. Runs and tracks work.xag_<prefix>_<secret>

Create a personal key

Auth: JWT access tokenfrom POST /api/auth/login

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

Create a runtime key

A runtime key is minted for a specific agent, either when you create the agent or afterwards:

POST /v1/agents/{agent_id}/api-key      # SDK surface
POST /api/agents/{agent_id}/api-key    # app surface

See Runtime Keys for the full request and response.

Sending a key

Authorization: Bearer xag_Ab3xY9_Qw7Rt2Kp9Lm4Nz8Vc1Bd6Hf5Jg0Xs3Tr

What makes a key stop working

Every authentication failure returns the same 401 invalid_api_key — deliberately, so keys cannot be probed. A key is rejected when it is missing or malformed, is the wrong type for the endpoint, has been revoked, has been paused, or (personal keys only) has passed its expiry. Runtime keys do not expire on their own.

JWT Access Tokens

The application API under /api authenticates with a JWT access token from sign-in rather than an API key:

POST /api/auth/login          # returns an access token and a refresh token
POST /api/auth/refresh
GET  /api/auth/me

Sign-in identifies you by email address, not username. Send the access token as Authorization: Bearer <access_token>. See Agents API for the full contract and error shapes.

Prefer API keys for integrations

JWT tokens are short-lived and tied to a person signing in. For anything long-running, use a personal or runtime key instead.

Keeping Keys Safe

  • Never commit a key to source control or expose one in client-side code.
  • The <prefix> is a public-safe 6-character handle — safe to log so you can tell which key is in use. The secret half is not.
  • Rotate any key you suspect is compromised. Rotating a runtime key invalidates the previous one immediately.
  • Prefer a runtime key scoped to one agent over a personal key when the integration only needs to run that agent.

Next Steps