Update API key

Outcome

Update the name, scopes, resource bindings, or expiry of one 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.update --detail --json
topolo apps --json
topolo whoami --json

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

Input fields

Effects

• Updates only the supplied name, scope set, resource bindings or lifetime after fresh selection-policy checks. Does not rotate or return the credential secret.

Interpret the response

data.key is the updated record. Omitted fields retain prior values. Scopes and resourceBindings replace the supplied sets; expiry updates are relative to the current time. No secret or stored hash is returned.

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",
  "name": "Reviewed documentation read key"
}

CLI:

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

MCP:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.api_keys.update",
    "input": {
      "apiKeyId": "key_minimal_fixture",
      "name": "Reviewed documentation read key"
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "API key updated 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": "active"
    }
  },
  "timestamp": "2026-10-02T14:48:16.390Z"
}

data.key is the updated record. Omitted fields retain prior values. Scopes and resourceBindings replace the supplied sets; expiry updates are relative to the current time. No secret or stored hash is returned.

Workflow example

Input · payload.json:

{
  "apiKeyId": "key_workflow_fixture",
  "name": "Reviewed documentation read key",
  "scopes": [
    "docs:read"
  ],
  "resourceBindings": [
    {
      "resourceType": "workspace",
      "resourceId": "ws_created_workflow"
    }
  ],
  "expiresInDays": 7
}

CLI:

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

MCP:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.api_keys.update",
    "input": {
      "apiKeyId": "key_workflow_fixture",
      "name": "Reviewed documentation read key",
      "scopes": [
        "docs:read"
      ],
      "resourceBindings": [
        {
          "resourceType": "workspace",
          "resourceId": "ws_created_workflow"
        }
      ],
      "expiresInDays": 7
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "API key updated 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": "active"
    }
  },
  "timestamp": "2026-10-02T14:48:16.406Z"
}

data.key is the updated record. Omitted fields retain prior values. Scopes and resourceBindings replace the supplied sets; expiry updates are relative to the current time. No secret or stored hash is returned.

Verify the result

• Read api_keys.list and compare the selected id and every requested change. Require canEdit before planning; other callers can manage this key only when their per-app capabilities allow it.

Errors and recovery

Captured local refusal · HTTP 404:

{
  "input": {
    "apiKeyId": "key_missing_fixture",
    "name": "Missing key"
  },
  "response": {
    "success": false,
    "error": {
      "message": "API key not found",
      "code": "NOT_FOUND",
      "details": null,
      "timestamp": "2026-10-02T14:48:16.393Z"
    }
  }
}

Save the prior name, scopes, bindings and expiry. Recheck api_keys.options before planning restoration of the reviewed fields. expiresInDays is relative, so this action does not accept an exact previous expiresAt timestamp or guarantee byte-identical expiry restoration.

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.