External / Partner API

The /v1/external surface is for applications that act on behalf of their own end users — a partner backend integrating Xagent, or an Xagent chat widget embedded in someone else's product. It is a different audience from the Workspace SDK: that surface authenticates your workspace with an xag_… key, whereas this one authenticates an application plus the end user it is acting for.

The Two Callers

Get a Token — POST /v1/external/oauth/token

Auth: No bearer authStripe signature verified

Standard OAuth 2.0 client-credentials exchange. Send it as form-encoded data (application/x-www-form-urlencoded) — JSON is rejected.

curl -X POST https://sg-origin.cloud.xagent.co/v1/external/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=agent:42"

Response (200): the token is valid for two hours.

{
  "access_token": "eyJhbGciOiJFZERTQSIs...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "agent:42"
}

This endpoint alone uses the OAuth error format, not the envelope used elsewhere on this surface:

{ "error": "invalid_client", "error_description": "Client authentication failed." }

Calling the API

Every other /v1/external request carries two headers — the token, and the end user you are acting for:

Authorization: Bearer <access_token>
X-Actor-Id: <your own opaque user id>

X-Actor-Id is your identifier for the user, up to 255 characters — never an Xagent user id. Xagent creates the actor record the first time it sees one. The older X-End-User-Id header is rejected.

Verifying Signatures — JWKS

GET /.well-known/jwks.json

Published key set, cacheable for five minutes. It contains two kinds of key: use: "sig" (Ed25519) for verifying signatures on refresh webhooks Xagent sends you, and use: "enc" (RSA) for encrypting widget grants before you send them. Select a signing key by matching the kid from the signature header — never by position in the array. For encryption, any listed enc entry is valid; copy its kid into your header.

Delegated OAuth Credentials

If your users connect third-party accounts, you push their short-lived access tokens to Xagent so agents can act with them. Xagent encrypts each token and stores it against the actor. These endpoints never return a token.

Push a credential — PUT /v1/external/oauth-tokens

Auth: Runtime keyxag_<prefix>_<secret>

Returns 204. The body takes one of two shapes and must match exactly one of them:

expires_at is an RFC 3339 timestamp and must be no more than 400 days in the future. Sending both resource and connector_ref returns 422. Bodies are limited to 64 KiB.

Revoke a credential — DELETE /v1/external/oauth-tokens

Auth: Runtime keyxag_<prefix>_<secret>

Returns 204. Choose one form — the two behave differently, and the difference matters:

DELETE /v1/external/oauth-tokens?resource=<uri-encoded>
DELETE /v1/external/oauth-tokens?connector_type=mcp&connector_id=7

Supplying only one half of the connector pair returns 422; supplying both forms together also returns 422.

Two further behaviours worth knowing: two connectors that derive the same resource for one actor share a single credential, so a later push replaces the earlier token and deleting through either revokes it; and revoking a credential causes a widget re-authorisation against it to be refused until you push a token again. If you ever mix the two forms for the same resource, keep the resource string on your side.

Tasks

Auth: Runtime keyxag_<prefix>_<secret>

Mirrors the Workspace SDK task endpoints and returns the same response shapes, scoped to the acting end user.

POST /v1/external/chat/tasks                      # 202 Accepted
GET  /v1/external/chat/tasks/{task_id}
POST /v1/external/chat/tasks/{task_id}/messages   # 202 Accepted
GET  /v1/external/chat/tasks/{task_id}/steps

Two differences from the Workspace SDK: the request body also accepts oauth_tokens (an array of { resource, access_token, expires_at } — the connector-reference form is not accepted here) and connector_runtime_context; and /steps returns a deliberately narrower, external-safe view of each step. Bodies are limited to 64 KiB, and unknown top-level fields are rejected with 422.

Files

Auth: Runtime keyxag_<prefix>_<secret>

Files belong to the acting end user; no request names a user or application id.

POST   /v1/external/files                    # 201 Created, multipart field "file"
GET    /v1/external/files
GET    /v1/external/files/{file_id}/content
DELETE /v1/external/files/{file_id}          # 204 No Content

{
  "file_id": "3f9a1c...",
  "filename": "invoice.pdf",
  "file_size": 248311,
  "mime_type": "application/pdf",
  "created_at": "2026-08-10T09:15:00Z"
}

Uploads are capped at 100 MB by default and rejected with 413 as soon as the limit is passed. Expect 401 for a bad token and 404 for a file that is not this user's.

Widget Sessions

Auth: No bearer authStripe signature verified

For an Xagent chat widget embedded in your product. Your backend mints a signed, encrypted context grant; the browser exchanges it for a session token.

POST   /v1/external/chat/sessions             # exchange a grant for a session
POST   /v1/external/chat/sessions/reconnect   # rotate tokens and resume
DELETE /v1/external/chat/sessions?actor_id=…  # 204, revoke all of one user's sessions

A session represents one browser conversation for a given application, end user and agent. It lives for 8 hours from creation — idle time does not extend it, and reconnecting does not either. Send the grant as { "encrypted_context": "…" }; no other fields are accepted. Both exchange and reconnect return the same shape:

{
  "session_token": "...",
  "session_token_expires_at": "2026-08-10T11:15:00Z",
  "reconnect_token": "...",
  "session": {
    "absolute_expires_at": "2026-08-10T17:15:00Z",
    "agent": { "id": 42, "name": "Support Bot", "description": "...", "logo_url": null, "suggested_prompts": [] }
  }
}

Reconnect rotates tokens on use and doubles as renewal — there is no separate renew call. Re-presenting a token inside its grace window replays the identical response; exceeding the reuse limit revokes the session.

Logout uses a query parameter rather than the usual header: DELETE /v1/external/chat/sessions?actor_id=…, authenticated with your client-credentials token. It revokes every one of that user's sessions regardless of the token's agent scope, and returns 404 actor_not_found for a user this application has never seen. Note that this form places user ids in URLs, so they may appear in proxy logs.

Grant and session errors use their own fixed code set, including grant_malformed (400), encryption_required (400), signature_invalid (401), grant_expired (401), grant_already_used (401), reconnect_invalid (401), session_expired (401), agent_not_granted (403), identity_mismatch (403), agent_not_available (409), widget_disabled (409), and rate_limited (429, with Retry-After).

Rate Limits

Grant exchange is limited to 1000 requests per minute per application, counted after signature verification, returning 429 rate_limited with a Retry-After header. A per-IP limit also applies at the proxy. Replaying an already-used grant still counts against the limit.

Real-Time Streaming

Two WebSocket endpoints stream a task as it runs.

On the backend socket, connect with no parameters and send task.create as the first frame, or attach to an existing task. Client frames are task.create, message.create and input.submit; server events include task.status, input.required, step.thinking, step.tool_call, step.agent_delegation, message.delta, message.completed, task.error and stream.resync_required. Frames are capped at 64 KiB and each application may hold 20 concurrent sockets; a widget session may hold 8.

Sequence numbers restart on every reconnect and there is no event replay, so when you receive stream.resync_required, fetch the task's steps over REST, reconcile, and resume. Disconnecting does not cancel a turn that is already running.

For the widget socket, only two close codes are terminal — 4403 (session or application revoked) and 4408 (session lifetime reached). Stop retrying on those. 4401, 4409, 1008 and 1011 are all recoverable by reconnecting.

Interaction-State Refusals

A message sent while a task is parked waiting on a question — or a stale/duplicate answer to one — produces a task.error whose socket stays open on both real-time endpoints, unlike the policy closes above. The client's next move (answer the pending question, or re-read it first) travels on the same connection, so nothing here should trigger a reconnect:

task_busy stays reserved for a genuinely in-flight turn (task status running) — the one case where "retry after it completes" is actually true.

On the widget session socket (/v1/external/chat/sessions/ws) specifically, a plain chat message sent while the bound task is parked on a pending question is not rejected with interaction_response_required. It is routed to the interaction continuation and delivered as the answer to that question instead — there is no separate answer frame on this transport, so the same frame shape means "new message" or "answer" depending on the task's current state. Which pending question it answers is inferred server-side from whatever is currently pending; a client that needs to be sure it is answering the question it is currently showing the visitor should re-read the task's state before sending if there is any chance the question rotated. The delivery still follows the ordinary message_accepted / message_rejected ack — a rejected delivery whose remedy is a fresh id carries retry_with_new_id: true on that ack.

A widget chat frame that starts a new turn (not an answer to a pending question) may also carry context.timezone — an IANA zone name the agent uses to render its clock and interpret relative wording like "tomorrow at 09:00" for that turn:

{ "type": "chat", "message": "Schedule this for tomorrow at 9am", "context": { "timezone": "Australia/Perth" } }

The bundled embed populates this automatically from the visitor's browser (or the embed's data-timezone attribute, if set). Each frame carries only its own value — a later frame that omits it does not inherit an earlier one — and a blank, non-string, or over-64-character value is treated as absent and degrades to UTC rather than rejecting the message. An answer to a pending question does not consume it; the resumed run keeps its original context.

Idempotent Task Creation (Command Recovery)

On the backend socket (/v1/external/chat/ws), task.create may include an optional data.command_id — a client-chosen identifier matching [A-Za-z0-9._:-]{1,64} that stays the same across retries of one logical create:

{
  "v": 1,
  "type": "task.create",
  "data": {
    "agent_id": 42,
    "message": {"role": "user", "content": "List my open tickets."},
    "command_id": "create-2026-08-11-001"
  }
}

This closes a gap where a task could be durably accepted and billed before the client learned its identity — a naive reconnect-and-retry then created a duplicate task. With a command_id supplied, the server persists the create binding, and a client that loses its connection before seeing the task id can safely resend the identical task.create:

• Same command_id, same payload: the server recovers the original task instead of creating a second one. The retry receives stream.resync_required (reason reconnected) followed by the task's current task.status; no new task is created, scheduled, or billed. The recovered connection is a full session — message.create and input.submit work as usual.
• Same command_id, different payload: the connection closes with policy code 1008 and reason create_command_conflict. This is stable — retrying the same pair conflicts again; use a new command_id to start a genuinely new task.

Recovery requires the deployment to configure a signing key set (XAGENT_EXTERNAL_CREATE_COMMAND_KEYS). On a deployment without keys configured, or once a binding's sealing key has been withdrawn, a task.create that carries a command_id closes with policy code 1008 and reason create_command_unverifiable; plain creates with no command_id are unaffected either way.

command_id is only supported on the backend socket. The widget socket (/v1/external/chat/sessions/ws) has its own delivery-probe idempotency via client_message_id and does not accept a create command id.

Error Format

This surface carries three different error shapes. Pick the right parser per endpoint:

When a capability is switched off for your tenant, the 404 uses { "detail": "…" } instead — the one exception to the above.

What Needs Confirming

Next Steps

• Workspace SDK → — the API for your own workspace
• API Reference → — surfaces, authentication and errors