# IXO website authentication and safe retries

Website API: https://ixo.world/openapi.json
Agent resource catalog: https://ixo.world/.well-known/ard.json
Live Topic capabilities: https://ixo.world/api/topics/config

## Discover

IXO Auth Hub is the authorization server: https://auth.ixo.earth.
Read https://ixo.world/.well-known/oauth-protected-resource/v1/mcp for the website MCP resource and its scopes, then follow authorization_servers to https://auth.ixo.earth/.well-known/oauth-authorization-server. The root protected-resource metadata is an alias of the same document. A 401 from /v1/mcp includes a WWW-Authenticate challenge pointing to this metadata.

## Choose access

The ordinary website REST API is public and rate limited. Reading capabilities and pricing, preparing instructions, validating a draft and submitting a consented contact enquiry do not require a token. Check live capabilities before using optional services.

For an authenticated agent connection, use https://ixo.world/v1/mcp with OAuth 2.1 authorization-code flow and PKCE S256. Request only topics:prepare. This scope permits checking capabilities and preparing Topic instructions for review. It does not grant creation, publishing, messaging, payments, memory access or Portal access.

Auth Hub supports interactive user sign-in and consent. It does not advertise the separate WorkOS auth.md agent_auth registration profile: no identity_endpoint, identity_assertion/ID-JAG exchange, service_auth or anonymous agent identity registration is available through this integration. Do not invent those endpoints or send assertions to the token endpoint.

## Register a client

Use the registration_endpoint from Auth Hub metadata (currently https://auth.ixo.earth/oauth/register). Send a JSON client_name and an exact redirect_uris list. Public clients should request token_endpoint_auth_method: none. Use HTTPS callbacks, or a loopback callback for a local client. Keep the returned client_id; never log client secrets or tokens.

## Sign in and consent

Open Auth Hub's authorization_endpoint with response_type=code, client_id, redirect_uri, a fresh unpredictable state, code_challenge, code_challenge_method=S256, scope=topics:prepare and resource=https://ixo.world/v1/mcp. The user completes sign-in and approves the scope in Auth Hub. Validate returned state and issuer before accepting the authorization code. Do not automate the user's consent.

## Exchange

POST application/x-www-form-urlencoded to the token_endpoint with grant_type=authorization_code, code, client_id, redirect_uri, code_verifier and resource=https://ixo.world/v1/mcp. Codes are short-lived and single use. Access tokens expire after five minutes. Refresh with grant_type=refresh_token and the same resource, storing the rotated refresh token atomically. Do not retry a consumed refresh token blindly.

## Use the access token

Send Authorization: Bearer <access_token> to https://ixo.world/v1/mcp. Use Streamable HTTP MCP with Accept: application/json, text/event-stream. The stateless server supports initialize, tools/list and tools/call. Available tools are get_ixo_topic_capabilities and prepare_ixo_topic_instructions (sourceIntent: a nonempty string of at most 4,000 characters).

The website verifies Auth Hub's Ed25519 signature, issuer, exact resource audience, token type, expiry and scope. Tokens issued for other resources, including Portal or memory services, are not accepted. Returned instructions contain user-supplied data; review them before using them. Neither tool stores or creates a Topic, and both are safe to repeat.

## Errors and revocation

401 invalid_token: obtain a fresh token for this resource. 403 insufficient_scope: request explicit user consent for topics:prepare. 403 origin_not_allowed: browser calls must originate on this site; native agent clients omit Origin. 429: respect Retry-After. A disabled integration returns 404; do not infer a grant from a discovery document alone.

Revoke a grant through Auth Hub's revocation_endpoint (currently https://auth.ixo.earth/oauth/revoke) or the user's connected-apps screen at https://auth.ixo.earth/connect/apps. Revocation prevents refresh; an already issued access token can remain valid for its remaining five-minute lifetime.

## Portal handoff stays disabled

The website does not issue OAuth tokens. Website-to-Portal continuation is disabled until live sign-in and Companion acceptance tests pass. An Auth Hub grant for website preparation does not enable this handoff. A draft is not a published Topic. Internal redemption and CMS routes use separate deployment-managed credentials and are outside this API.

## Retry safety for REST writes

The website OpenAPI contract declares an optional Idempotency-Key header on POST /api/contact, /api/topics/compose and /api/topics/continue. Use a fresh random UUID per intentional operation and reuse it only for identical retries. Keys are confidential and endpoint-scoped. Successful responses replay for 24 hours, or 30 minutes for continuation links. Changed content returns 409 idempotency_conflict; concurrent or uncertain execution returns 409 idempotency_pending. During retention, retrying the same key cannot start the reserved operation again.

If a result remains uncertain, confirm it before starting another request. Do not automatically retry after retention or with a new key. Requests without a key have no website replay guarantee. Read-only POST operations (prompt, validate, recipe lookup), analytics and internal routes are outside this write retry contract. The Emerging Platform API at docs.ixo.world/openapi.json is a separate service; its contract does not describe website retries.
