Launch Create

Outcome

Builds an Auth SSO authorize URL and attempts to record launch analytics and usage.

Before you start

• Verify the intended environment, authenticated identity and explicitly authorized ownership context.
• Discover the published launches:read permission and any required resource grant.
• Approve the actual effects before confirming the unchanged planned request. Fixture identifiers, recipients and provider responses authorize no live operation.

Discover the target

topolo whoami --json
topolo actions get app_topolo_one.launch.create --detail --json

• appId: Exact canonical application/service identifier from the discovery expected by this action; a display name is not an id.

Request

POST /api/launch/{appId}

Inspect and test this action.

Input fields

Inspect nested fields.

Interpret the response

Inspect app.id, launchUrl and expiresAt. Auth and the destination application authorize the actual handoff; the returned URL is not proof of successful login.

Inspect the declared output schema and captured variants.

Worked examples

Actual exported One Worker with local Miniflare D1/KV. Authentication, application discovery, checkout, billing and remote widget providers are controlled synthetic responses; outbound access is sealed. No live provider outcome is established.

Save the reviewed input below as payload.json; substitute discovered identifiers and bind credential/resource context separately. CLI:

topolo actions validate app_topolo_one.launch.create --data @payload.json --json
topolo actions plan app_topolo_one.launch.create --data @payload.json --json
topolo actions call app_topolo_one.launch.create --data @payload.json --confirm --detail --json

MCP planning and execution use the same reviewed input:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_one.launch.create",
    "input": {
      "appId": "fixture_launch_mail"
    }
  }
}

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_one.launch.create",
    "input": {
      "appId": "fixture_launch_mail"
    },
    "confirm": true,
    "detail": true
  }
}

Successful response · HTTP 200

Input · payload.json:

{
  "appId": "fixture_launch_mail"
}

Captured response:

{
  "launchUrl": "https://auth.test.com/sso/authorize?redirect_uri=https%3A%2F%2Fmail.test%2Fauth%2Fcallback&state=ae34167e-151b-4062-8e7d-96fa33f248c9&response_mode=sso_code&service=fixture_launch_mail&app_id=fixture_launch_mail",
  "app": {
    "id": "fixture_launch_mail",
    "name": "Mail",
    "description": "Launch Mail"
  },
  "expiresAt": "2026-10-06T01:44:00.925Z"
}

Inspect app.id, launchUrl and expiresAt. Auth and the destination application authorize the actual handoff; the returned URL is not proof of successful login.

Refused request · HTTP 401 · auth_error

Input · payload.json:

{
  "appId": "fixture_launch_mail"
}

Captured response:

{
  "error": "Token validation failed"
}

Authenticate using the required credential type for this action; service-only actions require the registered Auth service identity.

Successful response · HTTP 200

Input · payload.json:

{
  "appId": "launch-mail"
}

Captured response:

{
  "launchUrl": "https://auth.test.com/sso/authorize?redirect_uri=https%3A%2F%2Fmail.topolo.app%2Fauth%2Fcallback&state=99b90804-9241-401a-a4a8-5db7b38b98af&response_mode=sso_code&service=launch-mail&app_id=launch-mail",
  "app": {
    "id": "launch-mail",
    "name": "Mail",
    "description": "Launch Mail"
  },
  "expiresAt": "2026-10-06T01:44:00.036Z"
}

Inspect app.id, launchUrl and expiresAt. Auth and the destination application authorize the actual handoff; the returned URL is not proof of successful login.

Refused request · HTTP 502 · http_error

Input · payload.json:

{
  "appId": "launch-missing"
}

Captured response:

{
  "error": "Service metadata unavailable"
}

Inspect the retained raw error body and request details before correcting or retrying; this SDK code groups multiple distinct handler refusals.

Refused request · HTTP 401 · invalid_token

Input · payload.json:

{
  "appId": "launch-unauth"
}

Captured response:

{
  "error": "INVALID_TOKEN",
  "message": "Token validation failed"
}

Authenticate with a valid credential for the selected environment.

Verify the result

• Inspect app.id, launchUrl and expiresAt. Auth and the destination application authorize the actual handoff; the returned URL is not proof of successful login.

Errors and recovery

• auth_error (HTTP 401): Authenticate using the required credential type for this action; service-only actions require the registered Auth service identity.
• http_error (HTTP 502): Inspect the retained raw error body and request details before correcting or retrying; this SDK code groups multiple distinct handler refusals.
• invalid_token (HTTP 401): Authenticate with a valid credential for the selected environment.

These are observed local refusals; inspect the raw error body because one SDK code can represent several handler messages. Preserve the request id when available.

Recovery boundary

Repeated requests can add analytics events. Retain the intended launch context rather than retrying a completed launch blindly.

Related actions

• Launch Secure Token Create: Mint a short-lived token that carries the caller's identity into the launched app. It is refused when the caller is not entitled to that app.

Evidence

Actual exported One Worker with local Miniflare D1/KV. Authentication, application discovery, checkout, billing and remote widget providers are controlled synthetic responses; outbound access is sealed. No live provider outcome is established.