Get API key options

Resolve the caller's per-application key-management capabilities, scopes, and resources.

Outcome

Resolve the caller's per-application key-management capabilities, scopes, and resources.

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.options --detail --json
topolo apps --json
topolo whoami --json

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

Input fields

Field	Required	Meaning
`organizationId`	No	Active organization identifier from credential identity. It does not override the credential context; conflicting organization selections are refused.
`appId`	Yes	Exact target application identifier from credential-scoped discovery. Key grants and workspace policy are evaluated for this application.

Effects

Evaluates caller-specific API-key capabilities, scopes and permitted resource bindings without creating a credential.

Interpret the response

data.canCreate is the caller-specific creation decision; canManageOwnKeys and canManageOtherKeys are separate capabilities. resourceTypes describes selectors, not authorization. Use organizationWideScopes only without bindings, or the intersection of each selected resource.allowedScopes with bindings.

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.options --data @payload.json --json
topolo actions plan app_topolo_auth.api_keys.options --data @payload.json --json
topolo actions call app_topolo_auth.api_keys.options --data @payload.json --json

MCP:


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

Captured local handler response · HTTP 200:


{
  "success": true,
  "message": "API key options fetched successfully",
  "data": {
    "organizationId": "org_fixture",
    "appId": "app_topolo_docs",
    "serviceName": "Docs",
    "canCreate": true,
    "scopes": [
      {
        "id": "scope_docs_read",
        "app_id": "app_topolo_docs",
        "name": "docs:read",
        "description": "Read documentation",
        "resource_pattern": null
      }
    ],
    "organizationWideScopes": [
      {
        "id": "scope_docs_read",
        "app_id": "app_topolo_docs",
        "name": "docs:read",
        "description": "Read documentation",
        "resource_pattern": null
      }
    ],
    "resourceTypes": [
      {
        "resourceType": "workspace",
        "label": "Documentation workspaces",
        "emptyLabel": "No accessible workspaces"
      }
    ],
    "resources": [
      {
        "resource_type": "workspace",
        "resource_id": "ws_first_fixture",
        "label": "First reference",
        "status": "active",
        "accessLevel": "read_write",
        "allowedScopes": [
          "docs:read"
        ]
      },
      {
        "resource_type": "workspace",
        "resource_id": "ws_created_minimal",
        "label": "Reviewed integration reference",
        "status": "active",
        "accessLevel": "read_write",
        "allowedScopes": [
          "docs:read"
        ]
      }
    ],
    "canManageOwnKeys": true,
    "canManageOtherKeys": false
  },
  "timestamp": "2026-10-02T14:48:16.384Z"
}

Workflow example

Input · payload.json:


{
  "appId": "app_topolo_docs",
  "organizationId": "org_fixture"
}

CLI:


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

MCP:


{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.api_keys.options",
    "input": {
      "appId": "app_topolo_docs",
      "organizationId": "org_fixture"
    }
  }
}

Captured local handler response · HTTP 200:


{
  "success": true,
  "message": "API key options fetched successfully",
  "data": {
    "organizationId": "org_fixture",
    "appId": "app_topolo_docs",
    "serviceName": "Docs",
    "canCreate": true,
    "scopes": [
      {
        "id": "scope_docs_read",
        "app_id": "app_topolo_docs",
        "name": "docs:read",
        "description": "Read documentation",
        "resource_pattern": null
      }
    ],
    "organizationWideScopes": [
      {
        "id": "scope_docs_read",
        "app_id": "app_topolo_docs",
        "name": "docs:read",
        "description": "Read documentation",
        "resource_pattern": null
      }
    ],
    "resourceTypes": [
      {
        "resourceType": "workspace",
        "label": "Documentation workspaces",
        "emptyLabel": "No accessible workspaces"
      }
    ],
    "resources": [
      {
        "resource_type": "workspace",
        "resource_id": "ws_existing_fixture",
        "label": "Existing reference",
        "status": "active",
        "accessLevel": "read_write",
        "allowedScopes": [
          "docs:read"
        ]
      },
      {
        "resource_type": "workspace",
        "resource_id": "ws_created_workflow",
        "label": "Reviewed integration reference",
        "status": "active",
        "accessLevel": "read_write",
        "allowedScopes": [
          "docs:read"
        ]
      }
    ],
    "canManageOwnKeys": true,
    "canManageOtherKeys": false
  },
  "timestamp": "2026-10-02T14:48:16.403Z"
}

Verify the result

Require data.appId and organizationId to match the intended target. Stop when canCreate is false; never widen scopes beyond the returned selection policy.

Errors and recovery

This read creates no key. Preserve a denial; obtain the intended access through its authorized owner rather than changing credential context automatically.

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.