Using key value maps

This section discusses how to use key/value maps (KVMs).


There are times when you want to store data for retrieval at runtime—non-expiring data that shouldn't be hard-coded in your API proxy logic. Key value maps (KVMs) are ideal for this. A KVM is a custom collection of key/value String pairs that is either encrypted or unencrypted. Here are two examples:

KVMs have three broad uses cases (this list is just a guide to some different ways in which KVMs are used):

  • User session data: Data that is created (and destroyed) by the runtime. KVM entries can be encrypted or clear, with no ability to view or manage the entries outside the runtime. For example, shopping cart contents.
  • Configuration (such as routing rules and look up tables): Data is typically created outside the runtime but read by the runtime. This data is provided by the UI or API, and then made available to the gateway (as variables and read only).

    For example: You have an API proxy that needs to call one target (or Service Callout) URL in a test environment and another target URL in a production environment. Instead of hard-coding URLs in your proxy, you can have the proxy detect which environment it's in, execute the related KeyValueMapOperations policy, and retrieve the correct target URL from one of the KVMs you created.

    Later, if one or both of your targets change, you simply update the KVMs with the new URLs. The proxy picks up the new values, and no proxy redeployment is required.

  • Credentials: Store credentials, private keys, or tokens—like tokens for external services, credentials required to generate OAuth tokens, or private keys used in Java Callouts or JavaScript for encryption or JSON Web Token (JWT) signing. Instead of passing credentials, keys, or tokens in the request, or hard-coding them in your proxy logic, you can store them in a KVM (always encrypted) and dynamically retrieve them in calls to targets that require them.

You'll discover other situations where storage of key/value String pairs is useful. In general, consider using KVMs when:

  • Specific places in your code require different values at runtime.
  • Sensitive data needs to be passed without hard-coding it.
  • You want to store values that don't expire like a cache might.

In some cases, property sets are a good alternative to KVMs as they can be easier to use. For more information, see Caching.

About KVM scope

Scope means "where a KVM is available." KVMs can be created at the following scopes: organization, environment, and apiproxy.

For example, if key/value pairs are to be used for all APIs in an organization, create a KVM at the organization scope; or if only a specific API proxy should have access to keys/values, create the KVM at the apiproxy scope where only that API proxy can access the data.

Or you may want all API proxies in your test environment to have access to a key value map, in which case you'd create a key value map at the environment scope. Proxies deployed in the "prod" environment cannot access KVMs in the "test" environment scope. If you want the same KVM keys to be available in production, create a parallel KVM scoped to the "prod" environment.

If you want all proxies in all environments to access the same KVM, create the KVM at the organization scope.

Using KVMs

You can create and update KVMs in the following ways:

Using KVMs with the Apigee UI

You can use the Apigee UI to do the following tasks related to KVMs:

  • View a list of KVMs in an environment
  • Create a new (empty) KVM

Note that KVMs in the UI are scoped to an environment only.

You cannot currently add data to KVMs (even ones you create in the UI), delete KVMs, or view data in KVMs using the Apigee UI. You must use the KVM policies to add data to KVMs.

To create a new (empty) KVM or view a list of KVMs:

  1. Open the Apigee UI in a browser.
  2. Select Admin > Environments > Key Value Maps.
  3. From the environment drop-down list, select the environment you want.

    The Key Value Maps view displays a list of existing KVMs. If you have not created any KVMs, then the list of KVMs is empty.

  4. To create a new (empty) KVM, click the +Key value map button in the upper right.

    The Add key value map dialog appears:

    Add KVM in the UI

  5. In the Name field, enter a name for the KVM.

    The name can contain only letters, numbers, and hyphens. It cannot include spaces or other special characters. For example, enter "my-kvm-1".

  6. (Optional) Select the Encrypted checkbox. If you select this checkbox, Apigee encrypts the data in the KVM; otherwise, it is stored as clear text. For more information, see About encrypted KVMs.
  7. Click Add.

    Apigee creates the new KVM. You cannot edit the new KVM nor add data to it.

Using KVMs with the Apigee API

You can use Apigee APIs to create, list, and delete KVMs for the following scopes:

The /keyvaluemaps Apigee API lets you create and delete KVMs at all scopes (organization, environment, and apiproxy). You cannot add data to or update KVM data using the API.

To create an encrypted KVM with the Apigee API, add "encrypted":"true" to the JSON payload. You can only encrypt KVMs when you create them. You cannot encrypt an existing KVM.

Using KVMs with the KeyValueMapOperations policy

For runtime KVM creation and update by your API proxies, use the KeyValueMapOperations policy. (In the policy, you specify the name of the KVM in the mapIdentifier attribute on the parent element.)

The <InitialEntries> element lets you create and populate a baseline set of entries in a new KVM as soon as you save the policy in the UI or deploy the API proxy (if you developed it offline). If the values change in the policy, the existing values are overwritten. Any new keys/values are added to the existing KVM alongside the existing keys/values.

The <Put> element creates a new KVM if one doesn't already exist, and it creates a key with one or more values. If the KVM already exists, they key/values are added (or updated if the key already exists). You can use multiple <Put> elements in a KVM policy.

Trace and debug

When you use the KeyValueMapOperations policy to retrieve encrypted KVM values, you supply the name of a variable to store the value. To get an encrypted value, you need to add the private. prefix to the variable name, which prevents the KVM keys/values from appearing in Trace and debug sessions.

Retrieving KVMs

You retrieve encrypted and unencrypted key value maps with the KeyValueMapOperations policy. Use the policy's <Get> element to retrieve encrypted and unencrypted KVMs. To retrieve encrypted values with the policy, add a private. prefix to the name of the variable that will contain the retrieved value, as described in the Get operation section of the reference topic. That prefix hides the value from trace and debug sessions while you're debugging API proxies.

About encrypted KVMs

Encrypted KVMs are encrypted with an Apigee-generated AES-128 cipher key. The key used to encrypt a KVM is stored at the scope of the KVM. For example, within an organization, all encrypted KVMs you create at the environment scope are created using the same environment-scoped key.

Apigee handles the display of encrypted values in the following ways. (See Managing and using KVMs for information on creating encrypted KVMs.)

In the Apigee API, encrypted values are returned masked. Following is sample Apigee API response on a Get encrypted KVM call:

  "encrypted": true,
  "entry": [
      "name": "Key1",
      "value": "*****"
      "name": "Key2",
      "value": "*****"
  "name": "secretMap"