Secret References

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.

​

Supported Secret Managers

​

How It Works

1. You create a secret reference in Portkey via the API. The control plane stores only the reference configuration (manager type, secret path, auth config) — never the actual secret value.
2. At runtime, the data plane (AI Gateway) reads the reference configuration and fetches the secret directly from your external manager.
3. The control plane never fetches or sees the final secret. The data plane caches the fetched secret value for 5 minutes to avoid hitting your secret manager on every request. After the TTL expires, the next request triggers a fresh fetch.

​

Creating a Secret Reference

​

From the Control Panel

1. From your admin panel, go to Secret References and click Create.
2. Configure the reference identity:

• Name: A name for this reference
• Slug: Unique identifier, auto-generated from name if not added. Pattern: ^[a-zA-Z0-9_-]+$
• Description: Optional context about this reference’s purpose

3. Choose your external vault from the supported options:
   • AWS Secrets Manager
   • Azure Key Vault
   • HashiCorp Vault
4. Select the authentication type for your chosen manager and add the required details.
5. Secret Location:
   • Secret Path: Add the Secret name from the external manager
   • Secret Key (optional): Add the specific key within the secret

​

Via Admin APIs

{
  "name": "prod-openai-key",
  "manager_type": "aws_sm",
  "auth_config": {
    "aws_auth_type": "accessKey",
    "aws_access_key_id": "AKIA...",
    "aws_secret_access_key": "wJalr...",
    "aws_region": "us-east-1"
  },
  "secret_path": "prod/openai/api-key",
  "secret_key": "OPENAI_API_KEY"
}

​

Updating a Secret Reference

​

Deleting a Secret Reference

​

Workspace Scoping

• Pass allowed_workspaces with an array of workspace UUIDs or slugs when creating or updating the reference.
• This automatically disables allow_all_workspaces.

​

Auth Config

​

Secret Mappings

​

Schema

​

From the Control Panel

1. While creating a new LLM integration (or editing an existing one), you’ll see a toggle. Switch to Secret Ref to use the key via your vault.

2. Select the secret reference. Optionally, provide a Secret Key if the reference contains multiple values.

​

Via Admin APIs

​

Valid target_field Values

​

Example

{
  "secret_mappings": [
    {
      "target_field": "key",
      "secret_reference_id": "my-aws-api-key"
    },
    {
      "target_field": "configurations.aws_secret_access_key",
      "secret_reference_id": "aws-credentials-ref",
      "secret_key": "secret_access_key"
    }
  ]
}

​

Validation Rules

• secret_mappings must be an array (if provided).
• Each target_field must be one of the allowed fields/prefixes for the entity type.
• No duplicate target_field values within the array.
• Each secret_reference_id must reference an existing, active secret reference in the same organisation.
• If the entity is workspace-scoped, the secret reference must be accessible to that workspace (either allow_all_workspaces: true or explicitly mapped).
• On create, target_field values with the configurations. prefix are auto-normalized — you can pass just the field name without the prefix and it will be prepended.

​

Behavior

• At gateway runtime, mapped fields are resolved from the external secret manager using the referenced secret reference’s auth_config, secret_path, and the mapping’s secret_key (or the secret reference’s default secret_key).
• When a target_field of key is mapped, the key field on the entity becomes optional during creation.
• Secret mappings are returned in GET responses for integrations.

​

Sensitive Field Masking

​

Access Requirements

• Authentication: x-portkey-api-key header.
• RBAC Role: OWNER or ADMIN.

​

API Reference