Setting up API Access

Before you can access the Document Cloud API (DCAPI), you must first obtain an access token as follows:

  1. Create a certificate.
  2. Create an API key using the certificate containing the public key obtained in step 1.
  3. Create a JSON Web Token (JWT) using the API client credentials (the API key and secret, technical account ID, and organization ID).
  4. Sign the JWT using the private key associated with your API key so that Adobe can verify your identity.
  5. Request an access token by passing in the signed JWT as input.

After the credentials are validated, Adobe provides an access token that is valid for 24 hours. Your programs or scripts must pass the access token as part of every document cloud API call in the Authorization : Bearer header. This type of token cannot be refreshed. For complete details of this exchange, see Access API for Document Cloud.

Step 1: Create a Certificate

The certificate creation process produces both a public key and a private key. Adobe uses the public key to verify request credentials that you have signed with your private key. For creating or purchasing a valid digital signing certificate, see Certificates for Secure API Access.

You should secure your private key as it cannot be recovered or replaced. If you lose it or it is compromised, you must delete the corresponding certificate from your API key account. If necessary, you must create and upload a new certificate. Your API key must be associated with at least one valid certificate.

Step 2: Create an API Key

Each application is an API client and requires an API key. Note that in this context, an "application" is a script or service invoked from a server, and not an end-user mobile or web app. You might need only one such script or application for DCAPI access, but you could create more than one in order to track usage by application or to allow disabling one application without disabling the others.

To create the API key, make a request to the Document Cloud API Support team. A certificate containing the public key obtained in step 1 should be provided as part of the request as that is needed as input when creating API keys. You can associate more than one certificate with your API key. The API key uniquely identifies your API client.

You are responsible for saving and securing the credential values. You must protect them at least as well as you would protect an account name and password. The best practice is to store the key file in a credential management system or use a file system protection so that it can only be accessed by authorized users.

What's next

Your API client credentials consist of the API key and secret, technical account ID, and organization ID. Use these to create a JSON Web Token (JWT), and sign it with your private key. The JWT encodes all of the identity and security information that Adobe needs to verify your identity and grant you access to the DCAPI.

Public libraries are available for creating a JWT. The JWT must be digitally signed and base-64 encoded for inclusion in the access request. For details of what libraries are available and what fields must be included in your JWT, see Creating a JWT. See the NodeJS sample for a working example of creating access token using JWT in JavaScript.