Was this helpful?

To configure functionality that relies on public key infrastructure (SSL and SAML, for example) you need to create keystores and truststores that provide the necessary keys and X.509 digital certificates.


Supported key formats are:

  • PEM
  • DER
  • PKCS12
  • JKS (Can be imported directly without creating keystore)

Apigee Edge supports key sizes up to 2048 bits.

Create a JAR file containing your keystore

Create a JAR file with your key pair, certificate, and a manifest. The JAR file must contain the following files and directories:

  • /META-INF/descriptor.properties
  • myCert.pem
  • myKey.pem (Passphrase is optional)

Create a directory called /META-INF. Create a file called descriptor.properties in /META-INF with the following contents:


Generate the JAR file containing your key pair and certificate:

$ jar -cf myKeystore.jar myCert.pem myKey.pem

Add descriptor.properties to your JAR file:

$ jar -uf myKeystore.jar META-INF/descriptor.properties

Create keystore in an environment

You must upload the keystore file to an environment in your organization, and then reference this file in the element of SSL or SAML configuration.

First check your environment for any existing keystores:

$ curl -X GET https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores -u myname:mypass 

A default keystore is provided for free trial organizations. You should see:

[ "freetrial" ]

Check the contents of the keystore. At a minimum, you should see a single server SSL certificate--the default certificate that Apigee Edge provides for free trial accounts.

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial
  "certs" : [ "wildcard.apigee.net.crt" ],
  "keys" : [ "freetrial" ],
  "name" : "freetrial"

To create a different keystore in an environment:

Sample request:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores -H "Content-Type: text/xml" -d '<KeyStore name="myKeystore"/>'

Sample response:

  "certs" : [ ],
  "keys" : [ ],
  "name" : "myKeystore"

Upload keystore JAR to Apigee Edge

Once you have created a named keystore in the environment, you can upload a keystore as a JAR file as follows:

Sample request:

$ curl -u myname:mypass -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}&password={key_pass}"

This enables you to create your JAR files locally.

Verify that your keystore uploaded properly:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore -u myname:mypass 

Sample response:

{  "certs" : [ "myCertificate" ],
  "keys" : [ "myKey" ],
  "name" : "myKeystore"

You now have a private key available for mutual authentication between the specified environment in your organization on Apige Edge and your backend service. You can also use these keys for signing and encryption, when configuring SAML.

If you are using a self-signed certificate instead of a certificate issued by a CA, then you must import the self-signed certificate to the trust store on the target server. To do so, refer to the instructions for the target server where your backend service is deployed.

For usage, see Client-SSL to backend servers and Authenticate and authorize using SAML 2.0.


First, create an empty trust store in the environment.

$ curl -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u myname:mypass

Then upload the certificate to the trust store you created.

Note that in this example, the file that you upload is not a JAR file. Instead, it is a PEM file.

$ curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore" \
-u myname:mypass 

Then, reference the uploaded trust store by its alias in the SSL or SAML configuration file.

For usage, see Client-SSL to backend servers and Authenticate and authorize using SAML 2.0.

Get help

For help, see Apigee Customer Support.

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.