Certificates for Secure API Access

You must purchase or create a digital signing certificate for your organization before you can create your API key. A certificate defines a public key and a private key. In order to make calls to the User Management API, you package your API client credentials in a JSON Web Token (JWT) and sign it with the private key. Adobe uses the public key to authenticate the request.

When you create your own certificate, you create two separate files. One file contains the public key and another contains the private key. The public-key file can be in CRT, CER, DER, or PEM format. If you purchase a digital certificate, you might receive a PFX or PKCS #12 (.p12) archive file that contains both keys. In this case, you must extract the public key and save it to a public-key file. See Splitting a certificate file.

  • You must upload a public-key certificate file to the Developer Portal as part of creating your API key, and use the corresponding private key to sign JWTs that you create.
  • Your API key must be associated with at least one valid certificate. You can associate more than one certificate with your API key. If you do so, you can use the private key of any associated certificate to sign your JWT.
  • Adobe does not check for revocation or trust chains of the certificate. If you want to revoke a certificate that you have associated with an API key, you must do so explicitly using the Developer Portal. When you have done so, you can no longer use any JWT signed with the private key for that certificate to gain access to the User Management API.

To add or remove certificates, use the Developer Portal to edit and update your API key. See Replacing your certificate.

IMPORTANT The files that contains the public and private keys, but especially the private key, contain sensitive information. You must retain the private key securely. It cannot be recovered or replaced. If you lose it or it is compromised, you must delete the corresponding certificate from your account. If necessary, you must create and upload a new certificate. You must protect these files at least as well as you would protect an account name and password. The best practice is to store the key files in a credential management system or use file system protection so that it can only be accessed by authorized users.

Creating a self-signed certificate

You can create certificates in Windows with Cygwin, which includes openssl. In Mac OS, you can use the built-in command-line tool openssl. To create a certificate with the command-line tool, open a terminal window in Mac OS, or a Cygwin shell window in Windows, and run the platform-specific tool. In either case, the tool creates a public key in a certificate (CRT) file, and a private key.

The openssl req command creates a private-key file and a certificate (CRT) file containing the public key. During the key-generation process, you are prompted to enter additional information to create a DN (Distinguished Name) for the public key. You can accept default values in some cases. To leave a field blank, enter "." (a dot character).

For example:

$ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout private.key -out certificate_pub.crt

  Generating Generating a 2048 bit RSA private key
  ....................................................................................+++
  ............................+++
  writing new private key to 'private.key'
  -----

When the private key generation is complete, you see some instructions, and are prompted to enter DN information. For example:

  Country Name (2 letter code) [AU]: US
  State or Province Name (full name) [Some-State]: California
  Locality Name (eg, city) []: San Jose
  Organization Name (eg, company) [Internet Widgits Pty Ltd]: My Company
  Organizational Unit Name (eg, section) []: My Department
  Common Name (e.g. server FQDN or YOUR name) []: Jane Administrator 
  Email Address []: j_admin@my_company.com

The certificate generated by this command expires in 1 year (365 days), at which point you can create a new one. You can make the period longer, but rotating credentials periodically is a good security practice.

In this example, the new private key file is named "private.key". You use the private key to sign your JSON Web Token (JWT). The contents of the private-key file look something like this:

-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDuRjXRJVYouxCl
o5fMCikkjaEgaIN6hVqsyM8hzAXJkPglpB1tSwFy968+S/4YnLZ2sZs2WCM17oVX
…
ObGhwhcnvUoqweQ3rMlJH3nGVg==
-----END PRIVATE KEY-----

The command also creates a new certificate file named "certificate_pub.crt" that contains the public key. You must upload the certificate to the Developer Portal when you create the API key for access to the User Management API. The contents of the certificate file look something like this:

-----BEGIN CERTIFICATE-----
MIIEPTCCAyWgAwIBAgIJANU6Eel69NilMA0GCSqGSIb3DQEBCwUAMIG0MQswCQYD
VQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTERMA8GA1UEBwwIU2FuIEpvc2Ux
…
9ygguNdPe5SDGXueubbPVTEaee6mQamXhcnQ/1jQtNutUHJvwGng4MxLUkdim4/g
pqNlSLSXS26Dwu6qkBBpxdKA02qSK4lcfDkQwNR+ClrE
-----END CERTIFICATE-----

You can learn more about Open SSL and other command parameters here: https://www.openssl.org/docs/man1.0.2/apps/req.html.

Replacing your certificate

You must replace a certificate when it expires or is compromised. For a smooth transition from a certificate that is due to expire, initiate the replacement before the expiration date. As soon as you have associated a new certificate with your API Key you can begin using the new private key to sign requests. When all of your applications have been converted to use the new certificate, you can delete the old certificate from the API Key.

To associate a new certificate with your API key, follow these steps:

  1. Obtain or create the new certificate and private key file.
  2. Go to the Developer Portal and find your API Key entry.
  3. Click EDIT APP for your API Key.
  4. In the Certificates section, click Choose File and browse to the new certificate file.
  5. Click UPDATE API KEY.

You should now see two certificate entries for your API Key. To delete a certificate that has expired or been compromised:

  1. Go to the Developer Portal and find your API Key entry.
  2. Click EDIT APP for your API Key.
  3. Click the X by the expired or compromised certificate entry, then click UPDATE API KEY.

Splitting a single certificate file

If you purchase a certificate or obtain one from an internal department that manages security in your company, you typically receive a single file in PKCS#12 format (PFX), containing both the public and private keys. In some cases, the file might also contain additional information that is not needed for User Management access, and could interfere with processing.

You can use the openssl command-line tool to extract the certificate and private key from the single file. If necessary, you can then use a text editor to reformat the extracted certificate for use with the User Management API.

Extract keys

For example, this command extracts the certificate file from the PFX file:

$ openssl pkcs12 -in YourCertificate.pfx -out certificate_pub.cer -nokeys -nodes
  Enter Import Password:
  MAC verified OK

This command extracts the private key from the PFX file:

$ openssl pkcs12 -in YourCertificate.pfx -out private.key -nocerts -nodes
  Enter Import Password:
  MAC verified OK

IMPORTANT When you have extracted the private key file, it is no longer password protected. You must take extra measures to ensure its security such as storing it in a credential management system and setting file system permissions to restrict access to only authorized users.

Reformat extracted files

Open the files in a plain text editor. Do not use a word processing editor.

  • For the certificate file, remove any lines before or after the "-----BEGIN CERTIFICATE-----" and "------END CERTIFICATE-----" marker lines.
  • For the private key file, remove any lines before or after the "-----BEGIN PRIVATE KEY-----" and "------END PRIVATE KEY-----" marker lines.