Topolo Docs Topolo Platform
Open workspace

List launcher apps

Reads the caller’s Auth-backed launcher catalog.

Outcome

Reads the caller’s Auth-backed launcher catalog.

Before you start

  • Verify the intended environment, authenticated identity and explicitly authorized ownership context.
  • Discover the published apps:read permission and any required resource grant.

Discover the target

topolo whoami --json
topolo actions get app_topolo_one.apps.list --detail --json

Request

GET /api/apps

Inspect and test this action.

Input fields

Use an empty input object. Credential and resource context are separate.

Inspect nested fields.

Interpret the response

Inspect apps and total for this credential. The current handler can return HTTP 200 with an empty list when Auth discovery fails; emptiness does not prove there are no entitled applications.

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.apps.list --data @payload.json --json
topolo actions plan app_topolo_one.apps.list --data @payload.json --json
topolo actions call app_topolo_one.apps.list --data @payload.json --detail --json

MCP planning and execution use the same reviewed input:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_one.apps.list",
    "input": {}
  }
}

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_one.apps.list",
    "input": {},
    "detail": true
  }
}

Refused request · HTTP 401 · auth_error

Input · payload.json:

{}

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:

{}

Captured response:

{
  "apps": [
    {
      "id": "mail",
      "name": "Mail",
      "description": "Email",
      "base_url": "https://mail.topolo.app",
      "status": "active",
      "is_system_app": false
    }
  ],
  "total": 1,
  "user": {
    "id": "user_int_1",
    "role": "admin",
    "orgId": "org_int_1",
    "permissions": [
      "*"
    ]
  }
}

Inspect apps and total for this credential. The current handler can return HTTP 200 with an empty list when Auth discovery fails; emptiness does not prove there are no entitled applications.

Refused request · HTTP 401 · invalid_token

Input · payload.json:

{}

Captured response:

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

Authenticate with a valid credential for the selected environment.

Verify the result

  • Inspect apps and total for this credential. The current handler can return HTTP 200 with an empty list when Auth discovery fails; emptiness does not prove there are no entitled applications.

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.
  • 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

If unexpectedly empty, verify Auth discovery and active context before concluding that entitlements were removed.

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.