Revoke API key

Outcome

Revoke one central API key.

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.

• Validate and plan the exact request before execution. --confirm is a transport guard; the intended change must already be authorized.

Discover the target

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

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

Input fields

Effects

• Marks the selected central credential revoked. Retains its record; does not delete local protected references.

Interpret the response

data.key identifies the affected record and reports status revoked. No one-time secret or stored hash is returned. This response does not establish downstream cache propagation or delivery of a lifecycle notification.

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:

{
  "apiKeyId": "key_minimal_fixture"
}

CLI:

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

MCP:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.api_keys.revoke",
    "input": {
      "apiKeyId": "key_minimal_fixture"
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "API key revoked successfully",
  "data": {
    "key": {
      "id": "key_minimal_fixture",
      "name": "Reviewed documentation read key",
      "organizationId": "org_fixture",
      "appId": "app_topolo_docs",
      "userId": "usr_fixture",
      "scopes": [
        "docs:read"
      ],
      "resourceBindings": [],
      "expiresAt": 1798728496,
      "organizationName": "Fixture organization",
      "organizationSlug": "fixture",
      "serviceName": "Docs",
      "lastUsed": null,
      "createdAt": 1,
      "status": "revoked"
    }
  },
  "timestamp": "2026-10-02T14:48:16.392Z"
}

data.key identifies the affected record and reports status revoked. No one-time secret or stored hash is returned. This response does not establish downstream cache propagation or delivery of a lifecycle notification.

Workflow example

Input · payload.json:

{
  "apiKeyId": "key_workflow_fixture"
}

CLI:

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

MCP:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.api_keys.revoke",
    "input": {
      "apiKeyId": "key_workflow_fixture"
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "API key revoked successfully",
  "data": {
    "key": {
      "id": "key_workflow_fixture",
      "name": "Reviewed documentation read key",
      "organizationId": "org_fixture",
      "appId": "app_topolo_docs",
      "userId": "usr_fixture",
      "scopes": [
        "docs:read"
      ],
      "resourceBindings": [
        {
          "resourceType": "workspace",
          "resourceId": "ws_created_workflow"
        }
      ],
      "expiresAt": 1791557296,
      "organizationName": "Fixture organization",
      "organizationSlug": "fixture",
      "serviceName": "Docs",
      "lastUsed": null,
      "createdAt": 1,
      "status": "revoked"
    }
  },
  "timestamp": "2026-10-02T14:48:16.407Z"
}

data.key identifies the affected record and reports status revoked. No one-time secret or stored hash is returned. This response does not establish downstream cache propagation or delivery of a lifecycle notification.

Verify the result

• Read api_keys.list, locate the same id and require status revoked. Independently verify rejection through the intended credential-store integration before claiming downstream revocation proof.

Errors and recovery

No un-revoke action is published. Creating a replacement key is a separate reviewed access grant, not restoration of the same credential. Delete local protected references after use; local deletion alone does not revoke a key.

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.