portkey-admin-mcp

update_api_key

Update an existing API key's name, description, scopes, defaults, or limits without revoking it. Changes apply immediately, keeping the secret unchanged.

Instructions

Update an API key's name, description, scopes, defaults, or limits, unlike delete_api_key which revokes it or create_api_key which issues a new one. Changes take effect immediately for downstream callers, type and sub-type stay fixed after creation, and the call returns success without rotating the secret.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	The UUID of the API key to update
`name`	No	New display name for the key
`scopes`	No	New permission scopes for the key
`expires_at`	No	New expiration date in ISO 8601 format, or null to remove expiration
`description`	No	New description for the key
`rate_limits`	No	Replacement request or token rate limits, or null to clear
`reset_usage`	No	Set to a nonnegative acknowledgement value to reset usage
`alert_emails`	No	New email addresses for alerts
`credit_limit`	No	New credit limit for usage
`rate_limit_rpm`	No	New rate limit in requests per minute
`alert_threshold`	No	New alert threshold percentage (0-100)
`rotation_policy`	No	Replacement rotation policy, or null to disable it
`default_metadata`	No	New default metadata key-value pairs
`default_config_id`	No	New default configuration ID
`default_allow_config_override`	No	Whether callers may override the key's default config

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes	Whether the tool call succeeded and returned structured data
`data`	No	Structured success payload when ok is true
`error`	No	Structured error payload when ok is false

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.11.5Sep 8, 2026

addedInput schema / properties / default_allow_config_override

Added value: +{
+  "description": "Whether callers may override the key's default config",
+  "type": "boolean"
+}

changedInput schema / properties / expires_at / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "format": "date-time",
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / rate_limits

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "properties": {
+          "type": {
+            "description": "Whether the limit counts requests or tokens",
+            "enum": [
+              "requests",
+              "tokens"
+            ],
+            "type": "string"
+          },
+          "unit": {
+            "description": "Rate window unit for the request or token count",
+            "enum": [
+              "rpd",
+              "rph",
+              "rpm",
+              "rps",
+              "rpw"
+            ],
+            "type": "string"
+          },
+          "value": {
+            "description": "Maximum count in the selected rate window",
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "type",
+          "unit",
+          "value"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Replacement request or token rate limits, or null to clear"
+}

addedInput schema / properties / reset_usage

Added value: +{
+  "description": "Set to a nonnegative acknowledgement value to reset usage",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / rotation_policy

Added value: +{
+  "anyOf": [
+    {
+      "description": "Automatic API-key rotation policy, or null to remove it",
+      "properties": {
+        "key_transition_period_ms": {
+          "description": "Overlap in milliseconds before the previous key expires",
+          "maximum": 9007199254740991,
+          "minimum": 1800000,
+          "type": "integer"
+        },
+        "next_rotation_at": {
+          "anyOf": [
+            {
+              "format": "date-time",
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Explicit next rotation timestamp in ISO 8601 format"
+        },
+        "rotation_period": {
+          "anyOf": [
+            {
+              "enum": [
+                "weekly",
+                "monthly"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Built-in weekly or monthly automatic rotation cadence"
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Replacement rotation policy, or null to disable it"
+}

Addedv1.0.1May 7, 2026
RemovedMay 1, 2026
First observedJan 1, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnlyHint=false, destructiveHint=false, and idempotentHint=false, and the description adds meaningful extra context: changes take effect immediately for downstream callers, type and sub-type are immutable after creation, and the call does not rotate the secret. These are non-obvious behaviors an agent needs to know, and nothing contradicts the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no filler. The primary action is front-loaded, sibling differentiation comes second, and the behavioral caveats are packed into the final clause. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 15-parameter tool with nested objects, the description covers the core behavioral essentials (immediate effect, fixed type/sub-type, no rotation) and the output schema relieves it of explaining return values. A minor gap: it does not explicitly state whether omitted fields are left unchanged, which is material for an update operation with so many optional fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description's field list ('name, description, scopes, defaults, or limits') provides a compressed high-level map and groups related parameters, but it adds little meaning beyond what the schema's per-parameter descriptions already state. It does not, for example, explain update semantics like partial vs. full replacement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Update') plus resource ('API key') and enumerates the mutable attributes (name, description, scopes, defaults, limits). It explicitly names sibling tools it is not — delete_api_key (revokes) and create_api_key (issues new) — so an agent can disambiguate without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly contrasts update_api_key with delete_api_key and create_api_key, telling the agent when NOT to use it. The phrase 'returns success without rotating the secret' also implicitly routes secret-rotation intent to the rotate_api_key sibling. No inference is required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server