portkey-admin-mcp

create_api_key

Creates a Portkey API key for authentication with organisation or workspace scopes and returns the secret once; store it securely immediately.

Instructions

Create a Portkey API key for auth. Org keys grant broader access; workspace keys are scoped. WARNING: The key secret is returned ONCE in the tool result and will be visible in MCP transcripts and LLM context — store it securely immediately. Using the key grants access immediately according to its scopes, defaults, and limits. Workspace keys require workspace_id and user keys require user_id.

Input Schema

Name	Required	Description
`name`	Yes	Display name for the API key
`type`	Yes	Key type: 'organisation' for org-wide access or 'workspace' for workspace-scoped
`scopes`	Yes	Permission scopes for the key (e.g., ['logs.read', 'analytics.read'])
`user_id`	No	User ID (required for user sub-type keys)
`sub_type`	Yes	Sub-type: 'user' for user-associated keys or 'service' for service accounts
`expires_at`	No	Expiration date in ISO 8601 format
`description`	No	Optional description for the key
`rate_limits`	No	Request or token rate limits, or null to clear them
`alert_emails`	No	Email addresses for alerts
`credit_limit`	No	Credit limit for usage
`workspace_id`	No	Workspace ID (required for workspace-type keys)
`rate_limit_rpm`	No	Rate limit in requests per minute
`alert_threshold`	No	Alert threshold percentage (0-100)
`organisation_id`	No	Organisation UUID
`rotation_policy`	No	Automatic API-key rotation policy, or null to disable it
`default_metadata`	No	Default metadata key-value pairs
`default_config_id`	No	Default configuration ID to use with this key
`default_allow_config_override`	No	Allow callers to override the 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 / pattern

Previous value: -"^(?:(?:\\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)))$"New value: +"^(?:(?:\\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)))$"

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

Changed6 schema fields changedv0.11.5Sep 8, 2026

addedInput schema / properties / default_allow_config_override

Added value: +{
+  "description": "Allow callers to override the default config",
+  "type": "boolean"
+}

addedInput schema / properties / expires_at / format
```
Added value: +"date-time"
```

addedInput schema / properties / expires_at / pattern

Added value: +"^(?:(?:\\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)))$"

addedInput schema / properties / organisation_id

Added value: +{
+  "description": "Organisation UUID",
+  "type": "string"
+}

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": "Request or token rate limits, or null to clear them"
+}

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": "Automatic API-key rotation policy, or null to disable it"
+}

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

TDQS

A4.1/5.0

Behavior5/5

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

The description adds critical behavior beyond the annotations: the key secret is returned only once, will be visible in MCP transcripts and LLM context, and must be stored securely immediately. It also warns that the key grants access immediately according to its scopes, defaults, and limits. This is exactly the kind of security-sensitive behavioral context an agent needs for a create operation.

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

Conciseness4/5

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

The description is front-loaded with purpose, then gives key-type guidance and a prominent security warning. It is appropriately sized for a security-sensitive create tool, though the sentence about immediate access according to scopes/defaults/limits is slightly redundant with the earlier warning.

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?

Given an output schema, full parameter descriptions, and annotations, the description covers the most important missing context: one-time secret exposure and secure storage. It does not describe permission prerequisites for creating keys or contrast with sibling key-management tools, but it is largely complete for correct invocation.

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 schema already documents all 18 parameters thoroughly. The description repeats the workspace_id and user_id requirements and the org/workspace access distinction, but it does not add meaningful semantics beyond what the schema already provides. Baseline 3 is appropriate.

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 and resource: "Create a Portkey API key for auth." It also distinguishes org-wide vs workspace-scoped keys, so an agent can understand the tool's scope without opening the schema. The only minor gap is that it does not explicitly contrast with sibling tools like create_virtual_key, but the resource is clearly different.

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

Usage Guidelines3/5

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

The description gives useful context about key types and required IDs, but it does not explicitly say when to use this tool versus alternatives such as create_virtual_key, rotate_api_key, or create_access_policy. Usage is implied by "for auth" and the org/workspace distinction, but no exclusions or alternative routing are provided.

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

Deploy Server