Creating a JSON Web Token

To authorize access to the User Management API, you must use your API client credentials (API key and secret, API client account ID, and organization ID) 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 User Management API.

To initiate a user-management session, you use the JWT to obtain an access token from Adobe, make a POST request to:

https://ims-na1.adobelogin.com/ims/exchange/jwt/

The body of the request contains URL-encoded parameters with your API client ID, client secret, and JWT:

client_id=api_key_value&client_secret=client_secret_value&jwt_token=base64_encoded_JWT

For complete details of this exchange, see Access API for Document Cloud. This call is the equivalent of a log-in. The response contains an OAuth access token. The token is valid for a fixed period of time as configured for your application. You must pass a valid access token to each request that you make to the DCAPI.

Creation tools

Most modern languages have JWT libraries available. We recommend you use one of these libraries (or other JWT-compatible libraries) before trying to hand-craft the JWT token. For a sample that creates a JWT, see the NodeJS sample in the Document Cloud samples section. JWT libraries:

Language Library
Java atlassian-jwt and jsontoken
Python pyjwt
Node.js node-jwt-simple
Ruby ruby-jwt
PHP firebase php-jwt and luciferous jwt
.NET jwt
Haskell haskell-jwt

The JWT decoder is a handy web-based decoder for Atlassian Connect JWT tokens.

Build a JWT

Your JWT must contain the following claims:

Claim Description
exp Required. The expiration time, an absolute number of seconds since 1/1/1970 GMT. You must ensure that the expiration time is later than the time of issue. After this time, the JWT is no longer valid. An expiration period is typically one day.
iss Required. The issuer, your organization ID in the format org_ident@AdobeOrg. Identifies your organization that has been configured for access to the Document Cloud API.
sub Required. The subject, your API client account ID in the format: id@techacct.adobe.com.
aud Required. The audience for the token, in the format: https://ims-na1.adobelogin.com/c/api_key.
configured claims Required. The API-access claim configured for your organization: https://ims-na1.adobelogin.com/s/ent_documentcloud_sdk.
jti Optional. A unique identifier for the token, if configured for your organization. If required, you must use a decimal number greater than any valued used before, in order to prevent replay attacks. Otherwise, the request fails. To ensure an acceptable value, you can use the current Unix time (seconds since 1970).

The following is a sample payload to be signed and encoded.

{
  "sub": "12345667EDBA435@techacct.adobe.com",
  "iss": "8765432DEAB65@AdobeOrg",
  "exp": 1473901205,
  "aud": "https://ims-na1.adobelogin.com/c/1234-5678-9876-5433",
  "https://ims-na1.adobelogin.com/s/ent_documentcloud_sdk": true,
  "jti": "1470000000"
}

Sign and encode your JWT

The token must be signed using the private key corresponding to a public certificate that was used when creating your API key. You can associate more than one certificate with an API key. If you do so, you can use the private key of any associated certificate to sign your JWT. The JWT must be base-64 encoded for inclusion in the access request. The JWT libraries provide functions to perform these tasks.

Adobe supports the following digital signature and MAC algorithms:

Digital Signature or MAC Algorithm JWS "alg" Parameter Value
RSASSA-PKCS1-V1_5 Digital Signatures with with SHA-2 RS256, RS384 and RS512
Elliptic Curve Digital Signatures (ECDSA) with SHA-2 ES256, ES384 and ES512