portkey-admin-mcp

create_api_key

Create a Portkey API key for authentication with org-wide or workspace-scoped access. Provide workspace_id for workspace keys or user_id for user keys, and store the one-time secret securely.

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

TableJSON 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

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.

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?

Annotations only cover readOnly/openWorld/idempotent/destructive, so the description carries the safety burden and does it well: it discloses that the secret is returned ONCE, that it will be visible in MCP transcripts/LLM context, that the key grants access immediately, and that scope/defaults/limits apply at use. This is exactly the non-obvious behavioral context an agent needs.

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?

Front-loads purpose, then surfaces the security warning prominently, then the conditional requirements. Five sentences, each carrying weight; the warning sentence is long but justified given the stakes.

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 18-parameter mutation with an output schema (so return values need no explanation), the description covers purpose, type semantics, secret handling, and prerequisites. Minor gap: no mention of rotation policy behavior or idempotency impact of repeated calls, but overall sufficient.

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% across 18 parameters, so the schema already documents each field, including the conditional workspace_id/user_id requirements. The description restates the workspace_id/user_id conditions but adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

Purpose4/5

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

States a specific verb+resource ("Create a Portkey API key for auth") and contrasts org vs workspace key scope, so the core action is unambiguous. It does not, however, distinguish itself from adjacent siblings like create_virtual_key, rotate_api_key, or create_secret_reference, which an agent must pick between.

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?

Gives clear selection context ("Org keys grant broader access; workspace keys are scoped") and states concrete prerequisites (workspace_id for workspace keys, user_id for user keys), which routes the caller on type/sub_type. It stops short of naming alternatives or when NOT to use this tool.

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

Deploy Server