Skip to main content
Glama

create_api_key

Creates scoped Portkey API keys for organisation, workspace, user, or service authentication; returns the secret once, so 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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "type": "<type>",
      "sub_type": "<sub_type>",
      "name": "<name>",
      "scopes": "<scopes>"
    },
    "name": "create_api_key"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesDisplay name for the API key
typeYesKey type: 'organisation' for org-wide access or 'workspace' for workspace-scoped
scopesYesPermission scopes for the key (e.g., ['logs.read', 'analytics.read'])
user_idNoUser ID (required for user sub-type keys)
sub_typeYesSub-type: 'user' for user-associated keys or 'service' for service accounts
expires_atNoExpiration date in ISO 8601 format
descriptionNoOptional description for the key
rate_limitsNoRequest or token rate limits, or null to clear them
alert_emailsNoEmail addresses for alerts
credit_limitNoCredit limit for usage
workspace_idNoWorkspace ID (required for workspace-type keys)
rate_limit_rpmNoRate limit in requests per minute
alert_thresholdNoAlert threshold percentage (0-100)
organisation_idNoOrganisation UUID
rotation_policyNoAutomatic API-key rotation policy, or null to disable it
default_metadataNoDefault metadata key-value pairs
default_config_idNoDefault configuration ID to use with this key
default_allow_config_overrideNoAllow callers to override the default config

Output Schema

NameRequiredDescriptionDefault
okYesCall succeeded
dataNoSuccess payload
errorNoFailure details

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.16.5
    • changedOutput schema / properties / data / description
      Previous value: -"Structured success payload when ok is true"New value: +"Success payload"
    • changedOutput schema / properties / error / description
      Previous value: -"Structured error payload when ok is false"New value: +"Failure details"
    • changedOutput schema / properties / error / properties / details / description
      Previous value: -"Optional structured error details"New value: +"Extra error details"
    • changedOutput schema / properties / error / properties / message / description
      Previous value: -"Human-readable error message"New value: +"Error message"
    • changedOutput schema / properties / ok / description
      Previous value: -"Whether the tool call succeeded and returned structured data"New value: +"Call succeeded"
  2. Changed2 schema fields changedv1.0.9
    • 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"
  3. Changed2 schema fields changedv0.12.2
    • 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"
      +  }
      +]
  4. Changed6 schema fields changedv0.11.5
    • 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"
      +}
  5. Addedv1.0.1
  6. Removed
  7. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations declare a non-read-only, non-idempotent, non-destructive creation with openWorldHint=true, but they cannot convey the security-critical behavior the description does: the secret is returned ONCE and will appear in MCP transcripts and LLM context, so it must be stored immediately. It also discloses that the key is live and scoped as soon as it is created. This is exactly the context annotations cannot carry.

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?

Four tight sentences, each doing distinct work: purpose, key-type tradeoff, the one-time secret warning (front-loaded with 'WARNING:'), and conditional requirements. No restatement of the name or title, and the security warning is placed prominently rather than buried.

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 an 18-parameter mutation tool with an output schema and annotations, the description covers the highest-risk facts: the irrecoverable secret, immediate activation, and type-dependent required fields. Niceties like scope semantics, rotation policy behavior, or default config interaction are adequately delegated to the rich schema and output schema.

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% across 18 parameters, so the schema carries the parameter burden and baseline 3 applies. The description reinforces two conditional dependencies (workspace_id for workspace type, user_id for user sub-type) that are already documented in the schema descriptions, so it adds confirming rather than new meaning. Scope, rotation_policy, rate_limits, and the default_* fields are left entirely to the schema.

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?

The description opens with a specific verb and resource: 'Create a Portkey API key for auth.' It also distinguishes the two key types (organisation vs workspace) so an agent understands the object being produced. It does not, however, differentiate itself from the sibling create_virtual_key, which is a plausible source of confusion for an agent choosing a creation tool.

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?

It gives concrete selection criteria between key types: 'Org keys grant broader access; workspace keys are scoped,' and states the conditional requirements — workspace_id for workspace keys, user_id for user keys. What is missing is any explicit exclusion or pointer to an alternative tool (e.g., create_virtual_key) for related-but-different needs.

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

Deploy Server

Other Tools