Enforcing Request Metadata

Overview

Portkey allows organisation owners to define mandatory metadata fields that must be included with every API request. This feature enables granular observability across your organisation’s LLM usage.

How It Works

Organisation owners can define JSON schemas specifying required metadata properties for:

• API keys
• Workspaces

These metadata requirements are strictly enforced whenever:

• A new API key is created
• A new workspace is created

Existing API keys and Workspaces will not be affected by the new metadata schema. The new schema will only be enforced on NEW API keys, Workspaces or when existing API keys are updated.

Configuration

Setting Up Metadata Requirements

1. Head to Admin Settings on the Portkey dashboard
2. Navigate to the Organisation Properties section
3. Select either API Key Metadata Schema or Workspace Metadata Schema
4. Create a JSON schema specifying your required metadata fields
5. Add or modify the metadata schem. Save your changes

JSON Schema Requirements

The metadata schema follows JSON Schema draft-07 with certain modifications:

Required Schema Properties

• "type": "object" at the top level must always be present
• "additionalProperties": true must be present and always set to true
• Properties inside the schema must always have "type": "string"

Requirement	Description
"type": "object"	The top-level schema must be declared as an object
"properties": {...}	Define the metadata fields and their constraints
"additionalProperties": true	Additional properties must be allowed

Basic Schema

{
  "type": "object",
  "properties": {
    "team_id": {
      "type": "string"
    },
    "environment": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Schema With Required Fields

{
  "type": "object",
  "required": ["team_id", "service_id"],
  "properties": {
    "team_id": {
      "type": "string"
    },
    "service_id": {
      "type": "string"
    },
    "environment": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Schema With Default Values

{
  "type": "object",
  "properties": {
    "usertype": {
      "type": "string"
    },
    "environment": {
      "type": "string",
      "default": "dev"
    }
  },
  "additionalProperties": true
}

Schema With Enum Values

{
  "type": "object",
  "properties": {
    "use_case": {
      "type": "string",
      "enum": [
        "research",
        "instruction",
        "administrative"
      ]
    }
  },
  "additionalProperties": true
}

Using this Metadata in Portkey

Metadata validation on the schema is enforced on API Key/Workspace creation time.

When Creating API Keys

When creating a new API key (either Service or User type), you must provide metadata that conforms to the defined schema:

1. Navigate to the API Keys section
2. Click Create
3. Fill in the key details
4. In the Metadata field, provide a JSON schema with all required fields
5. If any required fields are missing, you’ll receive an error

When Creating Workspaces

When creating a new workspace, you must provide metadata that conforms to the defined schema:

1. Navigate to Workspaces on the left sidebar
2. Click +Add Workspace
3. Fill in the workspace details
4. In the Metadata field, provide a JSON schema with all required fields
5. If any required fields are missing, you’ll receive an error

Default Values

• Properties with default values will be automatically added if not specified
• User-provided values take precedence over default values

Metadata Precedence Order

When the same key appears at multiple levels, the precedence order is:

1. Workspace metadata (highest priority)
2. API key metadata
3. Request metadata (lowest priority)

Please note that before 1.10.20, the precedence order was:

1. Request metadata (highest priority)
2. API key metadata
3. Workspace metadata (lowest priority)

Best Practices

• Organisation owners should clearly communicate metadata requirements to all developers
• Maintain internal documentation of your metadata schema

Support

For questions about configuring metadata schemas or troubleshooting issues, contact Portkey support or reach out on Discord.