portkey-admin-mcp

update_api_key

Modify an existing API key's name, description, scopes, limits, defaults, or rotation policy without rotating its secret; changes apply immediately.

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

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

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.

Changed2 schema fields changedv1.0.9Oct 26, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed2 schema fields changedv0.12.2Oct 2, 2026

changedInput schema / properties / expires_at / anyOf

Previous 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"
-  }
-]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"
+  }
+]

changedInput schema / properties / rotation_policy / anyOf

Previous value: -[
-  {
-    "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"
-  }
-]New value: +[
+  {
+    "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"
+  }
+]

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.2/5.0

Behavior4/5

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

Annotations already declare mutation, non-idempotency and non-destructiveness; the description adds genuinely new behavior: changes propagate immediately to downstream callers, type/sub-type are immutable post-creation, and the secret is not rotated. It stops short of describing what callers in flight experience or what happens to fields omitted from the request.

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?

A single front-loaded sentence with three dense clauses: what is mutable, how it differs from siblings, and the runtime consequences. No filler and no repetition of schema detail.

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 15-parameter mutation with nested objects and an output schema, the description covers the highest-risk facts (immediate effect, immutable fields, no secret rotation). It does not warn that array fields like scopes, rate_limits and rotation_policy are full replacements rather than patches, which is the main remaining gap.

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 coverage is 100% with 15 well-documented parameters, so the schema carries the semantics. The description only groups fields loosely ('defaults', 'limits') and says nothing about reset_usage, expires_at, or the null-clears semantics for rate_limits/rotation_policy, so it adds no meaning beyond the schema.

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?

States a specific verb (update) plus resource (API key) and enumerates the mutable facets (name, description, scopes, defaults, limits). It explicitly distinguishes itself from delete_api_key and create_api_key, so an agent can route correctly without opening any sibling schema.

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

Usage Guidelines4/5

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

Names two alternatives and the conditions that select them (revoke vs issue new), and the clause 'without rotating the secret' implicitly deflects to rotate_api_key. However, the rotation sibling is never named explicitly even though it is the most confusable neighbor, and no preconditions (e.g. required permissions on the key) are stated.

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

Deploy Server