Creating a JSON Web Token

To authorize access to the Target 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 User Management. 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 User Management API.

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. Other JWT tools are publicly available, such as the JWT decoder, a handy web-based decoder for Atlassian Connect JWTs.

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

For an example Python script that creates a JWT, see the User Management Walkthrough.

Building 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 User Management 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_user_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_user_sdk": true,
  "jti": "1470000000"
}

Sign and encode your JWT

The JWT must be signed and base-64 encoded for inclusion in the access request. The JWT libraries provide functions to perform these tasks.

  • The token must be signed using the private key corresponding to a public-key certificate that is associated with 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. For more information, see Certificates for Secure API Access.
  • Adobe supports RSASSA-PKCS1-V1_5 Digital Signatures with SHA-2. The JWS algorithm ("alg") parameter value can be RS256, RS384, or RS512.