​
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"
RequirementDescription
"type": "object"The top-level schema must be declared as an object
"properties": {...}Define the metadata fields and their constraints
"additionalProperties": trueAdditional properties must be allowed

​
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.