Working with References

This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

When configuring a TargetServer to support TLS, you specify a keystore or truststore by using a reference. A reference is a variable that contains the name of the keystore or truststore, rather than specifying the keystore or truststore name directly.

A reference can be represented by an XML object like the one below:

<reference><name>ReferenceName</name><description>ReferencDescription</description><resourceType>ReferredResourceType<resourceType><refers>ReferredResource<refers></reference>

The advantage to using a reference is that you can change the value of the reference to change the keystore used by the target server, usually because the cert in the current keystore is expiring in the near future.

You can only use a reference to the keystore and truststore; you cannot use a reference to the alias. When you change the reference to a keystore, ensure that the alias name of the cert is the same as in the old keystore.

Restrictions on using references to keystores and truststore

If you have a load balancer and terminate TLS on the load balancer, then you cannot use keystore and truststore references in the target server.

Create a reference

You can use the Apigee UI or API to create a new reference.

Apigee UI

To create a reference using the Google Cloud console:

  1. In the Google Cloud console, go to theManagement> Environments page.

    Go to Environments

  2. Select the desired environment where you want to create the reference.

  3. Click theReferences tab.

  4. ClickCreate Reference.

  5. In theCreate Reference pane, enter the following details:
    • Name: The name of the reference.
    • Keystore: The keystore to which the reference points.

  6. ClickCreate.

API

To create a reference using theCreate Reference API call:

      curl -H "Authorization: Bearer $TOKEN" \        -X POST \        -d '{            "reference": {              "name": MyReferenceName",              "resourceType": "KeyStore",              "refers": "KeyStoreID"            }           }' \        https://apigee.googleapis.com/v1/{parent=organizations/*/environments/*}/references

Modify a reference

You can use the Apigee UI or API to modify an existing reference.

Apigee UI

To modify a reference using the Google Cloud console:

  1. In the Google Cloud console, go to theManagement> Environments page.

    Go to Environments

  2. Select the desired environment where you want to modify the reference.

  3. Click theReferences tab.

  4. In the displayed list, select the reference that you want to modify.

  5. ClickActions>Edit.

  6. In theEdit Reference pane, update the reference to specify the new keystore.

  7. ClickUpdate.

API

To change the reference to point to a different keystore, ensuring that the alias in the new keystore has the same name as the alias in the old keystore, use the Update Reference API:

        curl -H "Authorization: Bearer $TOKEN" \          -X PUT \          -d '{              "name": "MyReferenceName",              "resourceType": "KeyStore",              "refers": "KeyStoreID"              }' \        https://apigee.googleapis.com/v1/{name=organizations/*/environments/*/references/*}

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.