Prepare a customer connection

This page is for implementation operators and organisation owners. End users should start with Ask your agent to connect.

Prepare the Twin service

1. Deploy the central public gateway behind public HTTPS and configure its OAuth audience to exactly match the gateway origin.
2. Verify protected-resource and authorization-server metadata.
3. Register the tenant's trusted control-plane address.
4. Map the upstream organisation to exactly one Twin tenant and organisation.
5. Confirm the tenant's public app origin used for channel navigation.
6. Publish a new immutable Twin product version with reviewed public access.
7. Activate that version and bind any approved channel to the exact publication version.

Register the provider

Create one OAuth client per provider and tenant. Use the exact callback URL from the provider's setup screen, authorization-code and refresh-token grants, PKCE, and only:

• openid
• profile
• email
• mlx_tenant
• offline_access
• twin.query
• twin.read
• twin.write only when the client will expose approved posts, replies, records, or view mutations
• twin.connections when the agent will inspect or verify connections
• twin.onboarding when the agent will plan or resume setup

Store a returned client secret once in the provider's protected secret store. Do not place it in tickets, prompts, documentation, shell history, or source control.

Prove the real path

The connection is ready only when:

• the real user can sign in through the chosen provider;
• the provider exposes only the canonical twin_* channel, query, feedback, connection, and onboarding tools selected for that client;
• a missing connection or onboarding scope blocks its corresponding tool;
• setup resumes the same journey after reconnecting and rejects stale versions;
• business review and activation stop at explicit person-owned checkpoints;
• a natural question completes against exactly the intended product version;
• certificate evidence is present;
• approved channel links work and disappear for a user without access;
• cross-organisation, unapproved-product, missing-scope, expired-token, oversized-body, and rate-limit cases fail closed; and
• the organisation has recorded its ChatGPT, Claude, Codex, or other provider data-retention decision.

Use the gateway request ID, OAuth audit event, query/run identifiers, and execution certificate references for incident tracing. Do not add raw prompt or answer logging as a debugging shortcut.

The complete deployment, registration, and incident procedure remains in the repository runbook docs/runbooks/public-twin-connections.md.

Use the operator agent prompt when an authorised agent is guiding the onboarding journey.