List API keys

Outcome

List keys visible under the caller's per-application permissions, including per-key edit and revoke capabilities.

Before you start

• Verify the credential with topolo whoami --json and inspect the exact published action. Stop on runtime authorization denial; do not widen permissions or switch contexts automatically.

• Discover the target application and use the organization carried by the credential. A request organizationId is not a context override.

• Use api_keys.options for the exact application and active organization. Select resource bindings first, then the allowed scope intersection; general resource discovery alone is not key eligibility.

Discover the target

topolo actions get app_topolo_auth.api_keys.list --detail --json
topolo apps --json
topolo whoami --json

Inspect app_topolo_auth.api_keys.options before preparing credential creation or changes.

Input fields

Effects

• Lists only keys permitted by per-application capabilities and ownership. Returns edit/revoke decisions without key hashes or one-time secrets.

Interpret the response

data.keys is the visible key inventory. canEdit and canRevoke are per-record decisions. An empty list is a successful result; it does not establish that no keys exist outside the caller scope. Revoked records may remain in this inventory.

Worked examples

These are raw target-handler responses, not gateway or CLI envelopes. They were captured in a local test with simulated dependencies. Fixture identifiers and credentials are illustrative and cannot authorize a live call. Discover your own organization, application, workspace and key ids. Local CLI/stdio MCP may replace credential strings with protected references; preserve the reference and do not extract the underlying secret.

Minimal example

Input · payload.json:

{
  "appId": "app_topolo_docs"
}

CLI:

topolo actions validate app_topolo_auth.api_keys.list --data @payload.json --json
topolo actions plan app_topolo_auth.api_keys.list --data @payload.json --json
topolo actions call app_topolo_auth.api_keys.list --data @payload.json --json

MCP:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.api_keys.list",
    "input": {
      "appId": "app_topolo_docs"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "API keys fetched successfully",
  "data": {
    "keys": [
      {
        "id": "key_existing_fixture",
        "name": "Existing read key",
        "organizationId": "org_fixture",
        "organizationName": "Fixture organization",
        "organizationSlug": "fixture",
        "serviceName": "Docs",
        "lastUsed": null,
        "appId": "app_topolo_docs",
        "userId": "usr_fixture",
        "scopes": [
          "docs:read"
        ],
        "resourceBindings": [],
        "status": "active",
        "createdAt": 1,
        "expiresAt": null,
        "canEdit": true,
        "canRevoke": true
      }
    ]
  },
  "timestamp": "2026-10-02T14:48:16.386Z"
}

data.keys is the visible key inventory. canEdit and canRevoke are per-record decisions. An empty list is a successful result; it does not establish that no keys exist outside the caller scope. Revoked records may remain in this inventory.

Workflow example

Input · payload.json:

{
  "appId": "app_topolo_docs"
}

CLI:

topolo actions validate app_topolo_auth.api_keys.list --data @payload.json --json
topolo actions plan app_topolo_auth.api_keys.list --data @payload.json --json
topolo actions call app_topolo_auth.api_keys.list --data @payload.json --json

MCP:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.api_keys.list",
    "input": {
      "appId": "app_topolo_docs"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "API keys fetched successfully",
  "data": {
    "keys": [
      {
        "id": "key_existing_fixture",
        "name": "Existing read key",
        "organizationId": "org_fixture",
        "organizationName": "Fixture organization",
        "organizationSlug": "fixture",
        "serviceName": "Docs",
        "lastUsed": null,
        "appId": "app_topolo_docs",
        "userId": "usr_fixture",
        "scopes": [
          "docs:read"
        ],
        "resourceBindings": [],
        "status": "active",
        "createdAt": 1,
        "expiresAt": null,
        "canEdit": true,
        "canRevoke": true
      }
    ]
  },
  "timestamp": "2026-10-02T14:48:16.404Z"
}

data.keys is the visible key inventory. canEdit and canRevoke are per-record decisions. An empty list is a successful result; it does not establish that no keys exist outside the caller scope. Revoked records may remain in this inventory.

Verify the result

• Check each key organizationId/appId, scopes, bindings, expiry, status, canEdit and canRevoke before choosing a target. This read cannot recover a one-time secret.

Errors and recovery

This read changes no credential. Refresh discovery after a permission or ownership change.

Evidence boundary

The handler test proves response shape and control flow under the listed simulated dependencies. It does not prove real grant evaluation, durable SQL storage, protected credential-store handoff, target application synchronization or downstream use of a key.