Outcome
Returns One’s canonical v3 dashboard widget contract and current application-access metrics.
Before you start
- Verify the intended environment, authenticated identity and explicitly authorized ownership context.
- This route checks credential-scoped ownership and source access at runtime; validate the exact plan and resource binding.
Discover the target
topolo whoami --json
topolo actions get app_topolo_one.widget.get --detail --json
Request
GET /api/widget
Input fields
Use an empty input object. Credential and resource context are separate.
Interpret the response
Inspect success, contractVersion, appId and each widget id and source context. Widget availability does not establish access in another app.
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.widget.get --data @payload.json --json
topolo actions plan app_topolo_one.widget.get --data @payload.json --json
topolo actions call app_topolo_one.widget.get --data @payload.json --detail --json
MCP planning and execution use the same reviewed input:
{
"tool": "topolo_prepare_action",
"arguments": {
"actionId": "app_topolo_one.widget.get",
"input": {}
}
}
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_one.widget.get",
"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:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_one",
"serviceName": "TopoloOne",
"generatedAt": "2026-10-06T01:43:32.041Z",
"widgets": [
{
"id": "topolo-one.application-access",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Application access",
"description": "Applications available in the active organization.",
"contexts": [
"organization"
],
"supportedSizes": [
"compact",
"medium"
],
"defaultSize": "compact"
},
"resource": {
"resourceType": "organization",
"resourceId": "org_int_1",
"requiredPermissions": [
"widgets:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-06T01:43:32.041Z",
"lastSuccessfulAt": "2026-10-06T01:43:32.041Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 20,
"maxAgeSeconds": 300,
"staleWhileRevalidateSeconds": 300
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {}
},
"drilldowns": [
{
"id": "applications",
"label": "View applications",
"href": "/apps"
}
],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "one.widgets.applicationAccess.title",
"descriptionKey": "one.widgets.applicationAccess.description",
"title": "Application access",
"description": "Apps this workspace can open, and who has been granted them."
},
"accessibility": {
"label": "Application access metrics"
},
"contribution": {
"summary": "Applications available to the active organization.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "none",
"resourceType": "organization",
"label": "Active organization",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "applications",
"label": "Apps",
"description": "Applications available in the active organization.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
}
],
"seriesDefinitions": [],
"dimensions": [],
"lifecycleStages": [],
"events": [],
"datasets": [
{
"id": "application_access",
"label": "Application access",
"description": "Available application totals.",
"grain": "One aggregate row per active organization.",
"metricKeys": [
"applications"
],
"seriesKeys": [],
"dimensionKeys": [],
"eventKeys": [],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table"
],
"defaultVisualization": "number"
},
"metrics": [
{
"key": "applications",
"label": "Apps",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "1970-01-01T00:00:00.000Z",
"end": "2026-10-06T01:43:32.041Z",
"timezone": "UTC"
},
"dimensions": []
}
],
"appId": "app_topolo_one",
"serviceName": "TopoloOne",
"lastUpdated": "2026-10-06T01:43:32.041Z"
},
{
"id": "topolo-one.launch-activity",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Launch activity",
"description": "Measured application launches for the active organization.",
"contexts": [
"organization"
],
"supportedSizes": [
"compact",
"medium"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "organization",
"resourceId": "org_int_1",
"requiredPermissions": [
"widgets:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-06T01:43:32.041Z",
"lastSuccessfulAt": "2026-10-06T01:43:32.041Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 20,
"maxAgeSeconds": 300,
"staleWhileRevalidateSeconds": 300
},
"configuration": {
"allowMultipleInstances": false,
"fields": [],
"defaults": {}
},
"drilldowns": [],
"controls": [],
"localization": {
"locale": "en",
"titleKey": "one.widgets.launchActivity.title",
"descriptionKey": "one.widgets.launchActivity.description",
"title": "Launch activity",
"description": "Which apps people in this workspace have been opening."
},
"accessibility": {
"label": "Application launch activity metrics"
},
"contribution": {
"summary": "Application launch activity and outcomes for the active organization.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "none",
"resourceType": "organization",
"label": "Active organization",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "launches_today",
"label": "Launches today",
"description": "Application launches recorded today.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "total_launches",
"label": "Total launches",
"description": "All recorded application launches.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "successful_launches",
"label": "Successful launches",
"description": "Recorded application launches that succeeded.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "failed_launches",
"label": "Failed launches",
"description": "Recorded application launches that failed.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
}
],
"seriesDefinitions": [],
"dimensions": [],
"lifecycleStages": [
{
"key": "requested",
"label": "Requested",
"order": 0,
"terminal": false
},
{
"key": "succeeded",
"label": "Succeeded",
"order": 1,
"terminal": true
},
{
"key": "failed",
"label": "Failed",
"order": 2,
"terminal": true
}
],
"events": [
{
"key": "application_launched",
"label": "Application launched",
"description": "An application launch succeeded."
},
{
"key": "application_launch_failed",
"label": "Application launch failed",
"description": "An application launch failed."
}
],
"datasets": [
{
"id": "launch_activity",
"label": "Launch activity",
"description": "Application launch totals and outcomes.",
"grain": "One aggregate row per active organization and launch measure.",
"metricKeys": [
"launches_today",
"total_launches",
"successful_launches",
"failed_launches"
],
"seriesKeys": [],
"dimensionKeys": [],
"eventKeys": [
"application_launched",
"application_launch_failed"
],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"bar",
"table",
"funnel"
],
"defaultVisualization": "bar"
},
"metrics": [
{
"key": "launches_today",
"label": "Launches today",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-06T00:00:00.000Z",
"end": "2026-10-06T01:43:32.041Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "total_launches",
"label": "Total launches",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "1970-01-01T00:00:00.000Z",
"end": "2026-10-06T01:43:32.041Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "successful_launches",
"label": "Successful launches",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "1970-01-01T00:00:00.000Z",
"end": "2026-10-06T01:43:32.041Z",
"timezone": "UTC"
},
"dimensions": []
},
{
"key": "failed_launches",
"label": "Failed launches",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "1970-01-01T00:00:00.000Z",
"end": "2026-10-06T01:43:32.041Z",
"timezone": "UTC"
},
"dimensions": []
}
],
"appId": "app_topolo_one",
"serviceName": "TopoloOne",
"lastUpdated": "2026-10-06T01:43:32.041Z"
}
]
}
Inspect success, contractVersion, appId and each widget id and source context. Widget availability does not establish access in another app.
Refused request · HTTP 403 · permission_denied
Input · payload.json:
{}
Captured response:
{
"error": "INSUFFICIENT_PERMISSIONS",
"message": "Required permissions: widgets:read"
}
Discover the required permission and resource grants; re-authentication alone does not grant access.
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 success, contractVersion, appId and each widget id and source context. Widget availability does not establish access in another app.
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.permission_denied(HTTP 403): Discover the required permission and resource grants; re-authentication alone does not grant access.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
Re-read after access changes; this action does not execute any widget control.
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.