Secret References

Secret References let your organization point Portkey to secrets living in your own external secret manager. Instead of pasting provider keys or credentials directly into Portkey, you create a reference that tells Portkey where to fetch the secret at runtime. This keeps sensitive material in infrastructure you already control and audit.

Available on Enterprise plans only. Requires:

Gateway version 2.2.4 or higher
Backend version 1.12.0 or higher (for air-gapped deployments).

Supported Secret Managers

Manager	`manager_type` value
AWS Secrets Manager	`aws_sm`
Azure Key Vault	`azure_kv`
HashiCorp Vault	`hashicorp_vault`

How It Works

Secret references use a split architecture between Portkey’s control plane and data plane:

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.
At runtime, the data plane (AI Gateway) reads the reference configuration and fetches the secret directly from your external manager.
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

Send a POST request to /v1/secret-references with the following body:

{
  "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"
}

Field	Type	Required	Description
`name`	string	Yes	Display name (1–255 chars).
`slug`	string	No	Unique identifier. Auto-generated from name if omitted. Pattern: `^[a-zA-Z0-9_-]+$`.
`description`	string \| null	No	Max 1024 chars.
`manager_type`	string	Yes	`aws_sm`, `azure_kv`, or `hashicorp_vault`.
`auth_config`	object	Yes	Auth credentials for connecting to the manager. See Auth Config below.
`secret_path`	string	Yes	Path to the secret in the external manager.
`secret_key`	string \| null	No	Specific key within the secret (when the secret holds multiple key-value pairs).
`allow_all_workspaces`	boolean	No	Default `true`. Grant access to all workspaces.
`allowed_workspaces`	string[]	No	Restrict access to specific workspace UUIDs or slugs. Mutually exclusive with `allow_all_workspaces: true`.
`tags`	object \| null	No	Key-value metadata tags.

Updating a Secret Reference

Send a PUT request to /v1/secret-references/:id with only the fields you want to change. At least one field must be provided. auth_config updates are merged with the existing config - you don’t need to resend the full object. Setting allow_all_workspaces: true purges any workspace-specific mappings. Providing allowed_workspaces automatically sets allow_all_workspaces to false.

Deleting a Secret Reference

Send a DELETE request to /v1/secret-references/:id. It will fail if the secret reference is currently in use by any integrations or virtual keys - remove those associations first.

Workspace Scoping

By default, a secret reference is accessible from all workspaces in your organisation. To restrict access:

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

To revert to org-wide access, set allow_all_workspaces: true - this purges all workspace-specific mappings.

Auth Config

The auth_config schema depends on the manager_type you choose.

AWS Secrets Manager
Azure Key Vault
HashiCorp Vault

Access Key

Field	Type	Required
`aws_auth_type`	`"accessKey"`	Yes
`aws_access_key_id`	string	Yes
`aws_secret_access_key`	string	Yes
`aws_region`	string	Yes

Assumed Role

Use this when Portkey should assume an IAM role in your account.

Field	Type	Required
`aws_auth_type`	`"assumedRole"`	Yes
`aws_role_arn`	string	Yes
`aws_external_id`	string \| null	No
`aws_region`	string	Yes

Service Role

Uses Portkey’s own service role. Requires your secret’s resource policy to grant Portkey access.

Field	Type	Required
`aws_auth_type`	`"serviceRole"`	Yes
`aws_region`	string	No

Entra (Service Principal)

Field	Type	Required
`azure_auth_mode`	`"entra"`	Yes
`azure_entra_tenant_id`	string	Yes
`azure_entra_client_id`	string	Yes
`azure_entra_client_secret`	string	Yes
`azure_vault_url`	url	Yes

Managed Identity

Field	Type	Required
`azure_auth_mode`	`"managed"`	Yes
`azure_managed_client_id`	string	No
`azure_vault_url`	url	Yes

Default Credentials

Field	Type	Required
`azure_auth_mode`	`"default"`	Yes
`azure_vault_url`	url	Yes

Token

Field	Type	Required
`vault_auth_type`	`"token"`	Yes
`vault_addr`	url	Yes
`vault_token`	string	Yes
`vault_namespace`	string	No

AppRole

Field	Type	Required
`vault_auth_type`	`"approle"`	Yes
`vault_addr`	url	Yes
`vault_role_id`	string	Yes
`vault_secret_id`	string	Yes
`vault_namespace`	string	No

Kubernetes

Field	Type	Required
`vault_auth_type`	`"kubernetes"`	Yes
`vault_addr`	url	Yes
`vault_role`	string	Yes
`vault_namespace`	string	No

Secret Mappings

Secret mappings allow integrations and virtual keys to dynamically resolve secrets from secret references at runtime, instead of storing credentials directly. The secret_mappings field is an optional JSON array accepted on create and update for both Integrations and Virtual Keys.

Schema

Each entry in the secret_mappings array:

Field	Type	Required	Description
`target_field`	string	Yes	The field on the entity that should be populated from the secret reference. Must be unique within the array.
`secret_reference_id`	string	Yes	UUID or slug of the secret reference to resolve. Must belong to the same organisation and be accessible by the workspace.
`secret_key`	string \| null	No	Override the `secret_key` defined on the secret reference. Use to pick a specific key from a multi-value secret.

Valid `target_field` Values

Integrations (POST /v1/integrations, PUT /v1/integrations/:integrationId)

target_field	Description
`key`	The provider API key. When mapped, the `key` body field can be omitted.
`configurations.<field>`	Any provider-specific configuration field (e.g. `configurations.aws_secret_access_key`, `configurations.azure_entra_client_secret`).

Virtual Keys (POST /v1/virtual-keys, PUT /v1/virtual-keys/:virtualKeyId)

target_field	Description
`key`	The provider API key.
`model_config.<field>`	Any provider-specific model config field (e.g. `model_config.awsSecretAccessKey`, `model_config.vertexServiceAccountJson`).

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 entity-specific prefix (e.g. configurations. for integrations, model_config. for virtual keys) 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 both integrations and virtual keys.

Sensitive Field Masking

When you retrieve a secret reference via the API, sensitive auth_config fields are automatically masked. The original field is replaced with a masked_ prefixed version containing a truncated value.

Original Field	Masked Field
`aws_secret_access_key`	`masked_aws_secret_access_key`
`aws_access_key_id`	`masked_aws_access_key_id`
`aws_role_arn`	`masked_aws_role_arn`
`aws_external_id`	`masked_aws_external_id`
`azure_entra_client_secret`	`masked_azure_entra_client_secret`
`vault_token`	`masked_vault_token`
`vault_secret_id`	`masked_vault_secret_id`

Introduction

Product

Self-Hosting

Support

Supported Secret Managers

How It Works

Creating a Secret Reference

Updating a Secret Reference

Deleting a Secret Reference

Workspace Scoping

Auth Config

Access Key

Assumed Role

Service Role

Entra (Service Principal)

Managed Identity

Default Credentials

Token

AppRole

Kubernetes

Secret Mappings

Schema

Valid `target_field` Values

Example

Validation Rules

Behavior

Sensitive Field Masking

Access Requirements

API Reference

Create Secret Reference

List Secret References

Retrieve Secret Reference

Update Secret Reference

Delete Secret Reference

Introduction

Product

Self-Hosting

Support

​Supported Secret Managers

​How It Works

​Creating a Secret Reference

​Updating a Secret Reference

​Deleting a Secret Reference

​Workspace Scoping

​Auth Config

​Access Key

​Assumed Role

​Service Role

​Entra (Service Principal)

​Managed Identity

​Default Credentials

​Token

​AppRole

​Kubernetes

​Secret Mappings

​Schema

​Valid target_field Values

​Example

​Validation Rules

​Behavior

​Sensitive Field Masking

​Access Requirements

​API Reference

Create Secret Reference

List Secret References

Retrieve Secret Reference

Update Secret Reference

Delete Secret Reference

Supported Secret Managers

How It Works

Creating a Secret Reference

Updating a Secret Reference

Deleting a Secret Reference

Workspace Scoping

Auth Config

Access Key

Assumed Role

Service Role

Entra (Service Principal)

Managed Identity

Default Credentials

Token

AppRole

Kubernetes

Secret Mappings

Schema

Valid `target_field` Values

Example

Validation Rules

Behavior

Sensitive Field Masking

Access Requirements

API Reference