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
- Head to
Admin Settings
on the Portkey dashboard - Navigate to the
Organisation Properties
section - Select either
API Key Metadata Schema
orWorkspace Metadata Schema
- Create a JSON schema specifying your required metadata fields
- 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 totrue
- 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 |
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:
- Navigate to the API Keys section
- Click
Create
- Fill in the key details
- In the Metadata field, provide a JSON schema with all required fields
- 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:
- Navigate to Workspaces on the left sidebar
- Click
+Add Workspace
- Fill in the workspace details
- In the Metadata field, provide a JSON schema with all required fields
- 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
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.
Metadata Precedence Order
When identical metadata keys are passed at different levels (workspace settings, API key settings, or request level), Portkey follows this precedence order:
- Incoming request metadata (highest priority)
- API key metadata
- Workspace metadata (lowest priority)
This means that if the same key exists at multiple levels, the value from the incoming request will take precedence over the API key’s metadata, which in turn will override any workspace-level metadata setting for that key.
Was this page helpful?