> ## Documentation Index > Fetch the complete documentation index at: https://docs.portkey.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Enforcing Default Configs on API Keys > Learn how to attach default configs to API keys for enforcing governance controls across your organization ## Overview Portkey allows you to attach default configs to API keys, enabling you to enforce specific routing rules, security controls, and other governance measures across all API calls made with those keys. This feature provides a powerful way to implement organization-wide policies without requiring changes to individual application code. This feature is available on all Portkey plans. ## How It Works When you attach a default config to an API key: 1. All API calls made using that key will automatically apply the config settings 2. Users don't need to specify config IDs in their code 3. Administrators can update governance controls by simply updating the config, without requiring code changes This creates a clean separation between application development and governance controls. Create and manage configs to define routing rules, fallbacks, caching, and more ## Benefits of Default Configs Attaching default configs to API keys provides several governance benefits: * **Centralized Control**: Update policies for multiple applications by changing a single config * **Access Management**: Control which models and providers users can access * **Cost Control**: Implement budget limits and control spending across teams * **Reliability**: Enforce fallbacks, retries, and timeout settings organization-wide * **Security**: Apply guardrails and content moderation across all applications * **Consistent Settings**: Ensure all applications use the same routing logic ## Setting Up Default Configs ### Prerequisites Before attaching a config to an API key, you need to: 1. Create a [config](/product/ai-gateway/configs) on Portkey app with your desired settings 2. Note the config ID that want to attach to your API keys ### Attaching Configs via the UI Navigate to **API Keys** in the sidebar, then: * **New Keys**: Click **Create** and select your desired config from the **Config** dropdown * **Existing Keys**: Click the edit icon on any key and update the config selection * **Config Override**: Enable or Disable config override flag. * **ON** (default): Users can specify their own configs in requests, which will override the default config attached to the API key * **OFF**: Any attempt to override the default config in a request will result in a 400 error, enforcing the use of only the pre-approved config Admin API Key Config Selection You can attach only one config to an API key. This applies to both workspace API keys and admin API keys. ### Attaching Config via the API You can also programmatically attach config when creating or updating API keys using the Portkey API. #### Creating a New API Key with Default Config ```python theme={"system"} from portkey_ai import Portkey portkey = Portkey(api_key="YOUR_ADMIN_API_KEY") api_key = portkey.api_keys.create( name="engineering-team", type="organisation", workspace_id="YOUR_WORKSPACE_ID", defaults={ "config_id": "pc-your-config-id", "metadata": { "environment": "production", "department": "engineering" } }, scopes=["logs.view", "configs.read"] ) print(f"API Key created: {api_key.key}") ``` ```javascript theme={"system"} import { Portkey } from 'portkey-ai'; const portkey = new Portkey({ apiKey: 'YOUR_ADMIN_API_KEY' }); async function createApiKey() { const apiKey = await portkey.apiKeys.create({ name: 'engineering-team', type: 'organisation', workspace_id: 'YOUR_WORKSPACE_ID', defaults: { config_id: 'pc-your-config-id', metadata: { environment: 'production', department: 'engineering' } }, scopes: ['logs.view', 'configs.read'] }); console.log(`API Key created: ${apiKey.key}`); } createApiKey(); ``` ```bash theme={"system"} curl -X POST https://api.portkey.ai/v1/admin/api-keys \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \ -d '{ "name": "engineering-team", "type": "organisation", "workspace_id": "YOUR_WORKSPACE_ID", "defaults": { "config_id": "pc-your-config-id", "metadata": { "environment": "production", "department": "engineering" } }, "scopes": ["logs.view", "configs.read"] }' ``` #### Updating an Existing API Key For detailed information on API key management, refer to our API documentation: Learn how to create API keys with default configs Learn how to update existing API keys with new default configs ## Default Workspace User API Key Auto-Create Organisation owners can set **`default_workspace_user_api_key_auto_create`** (org-only, Backend `v1.17.0+`) to control whether workspace-user API keys are auto-provisioned when users join the organisation's **default workspace**. This is separate from per-workspace **`user_api_key_auto_create`** overrides. ## Workspace Default Config for User API Keys Organisation admins can set a workspace-level default config for workspace-user API keys via `defaults.user_api_key_config` on workspace create/update (Backend `v1.16.2+`). * Accepts a config **ID** or **slug** belonging to the workspace * **Auto-created** workspace-user API keys (from `user_api_key_auto_create`) inherit this config when no per-key default is set * **Manual** workspace-user API key creation falls back to this config when `defaults.config_id` is omitted * `GET` workspace returns the config **slug** in `defaults.user_api_key_config` * A config cannot be deleted while it is set as a workspace's `user_api_key_config` default ```json theme={"system"} { "defaults": { "user_api_key_config": "pc-your-config-id" } } ``` ## Embedding Default Configs in JWT Tokens If you use [JWT-based authentication](/product/enterprise-offering/org-management/jwt), you can also embed a default config directly in the JWT payload using the `defaults` claim — no need to attach it to an API key. This is useful when different users or services need different default configs, controlled at token issuance time. ```json theme={"system"} { "portkey_oid": "your-org-id", "portkey_workspace": "your-workspace", "scope": ["completions.write"], "exp": 1735689600, "defaults": { "config_id": "pc-your-config-id", "metadata": { "team": "backend" } } } ``` Learn more about embedding default configs in JWT tokens ## Config Precedence When using API keys with default configs, Portkey provides flexible options for controlling config behavior: * The default config attached to the API key will be automatically applied to all requests made with that key * By default, if a user explicitly specifies a config ID in their request, that config will override the default config attached to the API key * You can now disable config overrides by toggling off "Allow Config Override" when creating or editing API keys This flexibility allows for centralized governance while still enabling exceptions when needed. ## Use Cases ### Enterprise AI Governance For large organizations with multiple AI applications, attaching default configs to API keys enables centralized governance: 1. Create department-specific API keys with appropriate configs 2. Apply budget limits and define model usage per department 3. Track usage and spending per team by filtering logs by config\_id 4. Update policies centrally without requiring code changes ### Security and Compliance Ensure all API interactions follow security protocols by enforcing: * Specific models that have been approved for use * Content moderation with input/output guardrails * PII detection and redaction ### Cost Management Control AI spending by: * Routing to cost-effective models by default * Implementing caching for frequently used prompts * Applying rate limits to prevent unexpected usage spikes ## Support For questions about configuring default settings for API keys or troubleshooting issues, contact [Portkey support](mailto:support@portkey.ai) or reach out on [Discord](https://portkey.sh/reddit-discord).