Migration workspace
One workspace per partner connection, from the first question to monitoring. Both organizations work from the same immutable, hashed plan; each sees only what the other shared, and every high-impact step waits for its own approval.
What the workspace is
A connection workspace holds one relationship between a resource owner (the organization whose API is called) and a partner (the organization whose systems call it), for one endpoint. It references the organizations, the service, the invitation or grant and the gateway integration you already have; it never copies them. Open it in the portal under Migrations.
The aim is the smallest safe change that keeps the connection working: keep the gateway, the application and the server certificate, and move the calling side to a private client certificate that the gateway trusts next to the current one until the new path is proven. Mutual Trust does not promise an interruption-free or one-click migration; the tests in the plan decide when cutover may happen.
- Each side has its own view. The resource owner and the partner see their own evidence, receipts and approvers, plus what the other side deliberately shared (redacted). A delegated engineer sees only the discovery task.
- Request, identity proof, trust-anchor acceptance, resource authorization, configuration execution and production cutover are separate approvals. Trust in a certificate chain never grants access on its own: the resource owner authorizes each partner identity for the resource.
The nine steps
| Step | What happens |
|---|---|
| 1. Recognize the connection | The organizations, the endpoint, who owns the resource, why it may need to change and any deadline. A partner can propose a workspace by the owner's partner handle; the owner authorizes it, or, when the owner's policy does not take proposals, it stays a private assessment the owner does not see. |
| 2. Identify the environment | "What system are you trying to keep connected?" Name the platform, upload a sanitized configuration or a public client certificate, run a read-only inspection with mt discover, or say you are not sure. |
| 3. Delegate discovery | Invite the network or security engineer to a task-scoped, expiring discovery task. They do not join your organization. |
| 4. Assess | The clientAuth EKU, issuer, validity against the cutoff, trust anchors, authorization mapping, TLS termination and gateway limitations, each labelled verified, inferred or unknown with the evidence it rests on. |
| 5. Plan | What stays and what changes, who does what, impact, approvals, tests and rollback, in plain language, with a technical drill-down and the plan hash. |
| 6. Execute | The approved plan runs step by step, guided or through an approved connector, with evidence for each step. |
| 7. Validate and cut over | Positive and negative tests, then an approved cutover. Old trust is retired only after the new path is proven. |
| 8. Handover | A signed, role-scoped report with approvals, change version, test evidence, certificates, timeline and rollback record. |
| 9. Operate | Observed traffic and its coverage, certificate renewal and revocation, partner access and the audit log, in the same workspace. |
The public TLS clientAuth change is a forcing function for client certificates issued by publicly trusted TLS CAs with the clientAuth EKU. Mutual TLS with private-CA client certificates is not affected, and the assessment says so when that is what the evidence shows.
Discovery and delegation
Step 2 shows the exact commands for the workspace endpoint. Every collector is read-only; run the ones you can reach. See Migration discovery for what each collector observes.
mt discover endpoint api.example.com:8443 --http-probe --out endpoint.json
mt discover config /etc/nginx --out config.json
mt discover certs /path/to/client.p12 --target api.example.com:8443 --out certs.json
export MT_API_KEY=mtk_... # an API credential of your organization
mt discover report --from endpoint.json --from config.json --from certs.json --submit --workspace cws_...When you are not sure what runs at the gateway, delegate. Step 3 creates a task for the engineer's email with an expiry (up to seven days) and a scope: reading the evidence they submit, submitting discovery evidence, or both. The task link is shown once. The link alone grants nothing: the engineer signs in with a passkey or your organization single sign-on and claims the task, and the claim is recorded in your audit log. The claimed task page shows the same commands with MT_TASK_TOKEN instead of an API credential; the token works only for that workspace's discovery, until the task expires or you revoke it. The engineer can also upload a sanitized configuration from the portal.
Submitted text is untrusted. Text that reads like instructions is withheld from evidence and flagged; it never changes a plan, an approval or what any tool may do.
Plans and approvals
A plan is drafted from the latest assessment and is immutable: its hash is the SHA-256 of its canonical JSON. A new version supersedes the old one and invalidates the approvals recorded for it. Each approval is bound to the plan hash, the action, the target, the acting organization or person, the environment and an expiry, and is recorded from a signed-in browser session (step-up with your passkey or single sign-on when the approval policy asks for it). API credentials cannot approve.
- Resource owner: starting the execution, trust-anchor acceptance on the gateway, resource authorization of the partner, and cutover.
- Partner: identity proof (enrolling the workload through the existing issuance API) and the client configuration change.
- No self-approval of mandatory controls. Whoever drafted the plan cannot approve trust-anchor acceptance, resource authorization or cutover; another eligible person does.
The execution mode changes who performs a step, never which approvals it needs. Guided: you apply each change with the plan and the gateway's guided steps, then record the evidence. Automated: an approved, narrowly scoped connector (mt-adapt, see Integration adapters) applies the exact approved change to a registered integration. Agent-driven: an AI agent connected through the MCP server drafts, asks for approvals and drives the execution inside an agent run you create for one workspace side, with a mode (observe, supervised or delegated), a tool scope and an expiry. It never approves: you and your approvers do, and an approval for an action the agent performs names its run. You can pause, resume or cancel the run at any time; cancelling does not undo committed changes.
Execution, validation and cutover
The execution is durable: each step has an idempotency key, a receipt and, for configuration changes, before and after fingerprints. A step waits for its approval and its evidence; the workspace says what it is waiting on. For the partner's certificate, the step completes once the workload enrolls with mt enroll.
Validation needs a result for every test in the plan: the authorized client is allowed, and a request without a certificate, a certificate from an unknown issuer and a certificate that chains to the accepted CA but is not authorized for the resource are denied. Each result says whether it came from an active test request or observed production traffic. Cutover can be approved and requested only after validation passed; with old and new trust in parallel, existing certificates keep working until then. The after-cutover test proves the old credential is refused.
Rollback needs its own approval. It restores captured configuration step by step and suspends the partner grant rather than revoking it. It never claims to undo a revocation or an issued certificate, and the rollback record says what was undone, what cannot be and what needs a person.
Handover and operation
Once the connection is active (or rolled back), each side can download its handover report as JSON, with a JWS statement over the report hash signed by the trust space's manifest key and the public key to verify it offline. Each report shows that side's approvers, receipts and fingerprints; the other side appears by role only.
Step 9 stays with the connection: signed receipts from paired enforcers with their coverage (when nothing has been observed, the workspace says so instead of guessing), the certificates with their state and expiry, renewal with mt renew, partner access (suspend, withdraw or offboard from the grant) and the audit log.
API
The portal uses the public API; the same operations are available to your own tooling. See the API reference for the schemas.
| Operation | Purpose |
|---|---|
POST /v1/workspaces, GET /v1/workspaces/{id} | Create (owner side with service_id, partner side with owner_handle) and read a workspace in your view. |
POST /v1/workspaces/{id}/authorize | The resource owner binds a partner's proposal to a service. |
POST /v1/workspaces/{id}/assessments, GET /v1/workspaces/{id}/diagnostics | Submit evidence (MigrationEvidenceV1 documents, uploads, certificates or answers) and read the evidence you may see. |
POST /v1/workspaces/{id}/tasks, POST /v1/tasks/{id}/claim, POST /v1/tasks/{id}/revoke | Delegate, claim and revoke discovery tasks. |
POST /v1/workspaces/{id}/plans, GET /v1/plans/{id}, POST /v1/plans/{id}/approvals | Draft a plan version, read it, record an approval or rejection. |
POST /v1/plans/{id}/executions, GET /v1/executions/{id}, POST /v1/executions/{id}/evidence | Start the execution, follow it, record step evidence and test results. |
POST /v1/executions/{id}/cutover, POST /v1/executions/{id}/rollback | Request the approved cutover or rollback. |
GET /v1/workspaces/{id}/handover | The signed handover report for your side. |
POST /v1/workspaces/{id}/assessments/preview, POST /v1/workspaces/{id}/plans/preview | Assess evidence or draft the next plan version without storing anything. |
GET /v1/plans/{id}/readiness, GET|POST /v1/plans/{id}/approval-requests | What the next action still needs, checked as the action would check it; ask people for those approvals. |
POST /v1/workspaces/{id}/agent-runs, GET /v1/agent-runs/{id}, GET /v1/agent-runs/{id}/actions | Delegate to an agent, read a run and every call it made. |
POST /v1/agent-runs/{id}/pause, /resume, /cancel, /complete | Stop, continue or end an agent run (cancel can revoke its MCP credential). |
POST /v1/tasks/{id}/link | Issue the claim link of a pending task (for tasks an agent created, which never receives it). |