# 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
Paginated draft kinds: https://ixo.world/api/topics/kinds?limit=2

## 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 preparation and contact REST routes are public and rate limited; GET /api is the authenticated resource entry point. 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 also supports the WorkOS auth.md service_auth profile for agents that cannot receive an OAuth callback. Discover agent_auth in Auth Hub metadata and read its skill at https://auth.ixo.earth/auth.md. Only service_auth is supported; external identity assertions and anonymous identities are not accepted.

## Connect without an OAuth callback

Ask the user which email they use with Auth Hub. POST application/json to the discovered identity_endpoint (https://auth.ixo.earth/agent/identity):

```json
{"type":"service_auth","login_hint":"USER_EMAIL","client_name":"My personal agent","resource":"https://ixo.world/v1/mcp","scope":"topics:prepare"}
```

Keep claim_token secret. Show the user claim.verification_uri and claim.user_code. The user opens Auth Hub, signs in if needed, types the code and explicitly approves Topic preparation. Do not fill the code or consent for the user. Poll token_endpoint with application/x-www-form-urlencoded, grant_type=urn:workos:agent-auth:grant-type:claim and claim_token. Wait at least claim.interval seconds between polls; authorization_pending means wait, slow_down means increase the interval, access_denied means stop, expired_token means ask before starting again.

After consent the response includes access_token and identity_assertion. Keep both secret. The assertion lasts up to one hour from registration; exchange it at token_endpoint with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, assertion and the same resource. No refresh token is issued for this route. Revocation or expiry requires a new user-approved connection. This does not connect a Companion or enable Portal handoff.

## 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. GET https://ixo.world/api is a REST view of the same protected preparation resource and uses the same audience and scope. 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 standalone Emerging Platform API at docs.ixo.world/emerging/openapi.json is a separate service. The combined docs.ixo.world/openapi.json discovery contract also includes selected website operations with explicit website servers.

## Public catalogue pagination

GET /api/topics/kinds?limit=2 returns pinned draft kinds with items, next_cursor, has_more, total, protocolVersion and sourceCommit. Follow next_cursor (URL-encoded) or the Link rel=next header until has_more=false. The default limit is 10, maximum 20. Malformed cursors return 400; a cursor from an older catalogue returns 409 cursor_expired, requiring a fresh traversal. This catalogue is public and does not enable the optional live recipe indexer or Portal continuation.
